Alia is a Linux-only, fully local coding-agent launcher. It detects NVIDIA GPU, VRAM, and RAM, selects a hardware profile, starts llama-server, and opens a branded Qwen Code terminal or Web Shell. It does not implement its own agent loop or inference engine.
Measured on an RTX 3070 8 GB, Ryzen 7 5800X, 16 GB RAM — launch configuration
Qwen3.6 35B-A3B IQ3_XXS (default, context 65,536): 49.9 / 39.1 / 37.4 tok/s generation and 1,034 / 1,451 / 1,330 tok/s prompt processing at 4K / 32K / 60K (run llamacpp-20261017-234751, Alia's llama.cpp build, exact profile flags). The 4K speed is stable (46.5–49.9 tok/s over four runs). Deep-context speed depends on free RAM: when other apps push the 13 GB model out of the page cache, it streams from the SSD and drops to 24.6 tok/s at 32K and 9.7 at 60K (run llamacpp-20261015-101143). Use 32 GB RAM for long contexts, or close the browser. Alia warns at startup when less than 11 GB RAM is available, and alia doctor shows the free RAM.
Qwen3.5 9B Q4_K_M (fast, context 65,536): 66.2 / 57.8 / 51.4 tok/s generation and 2,964 / 2,695 / 2,424 tok/s prompt processing at 4K / 32K / 60K (run llamacpp-20261017-235521).
TG means token generation rate; PP means prompt-processing rate. MTP is multi-token prediction (speculative decoding using the model's MTP heads). Exact run and context provenance lives beside every numeric metric in profiles.json.
Quality scores (35B: code 9/10, tools 7/8, JSON 3/3 with schema and 3/3 prompt-only; 9B: code 8/10, tools 8/8) come from separate quality runs whose server context and arguments were not recorded; the 9B quality run used Ollama.
Supported platform and prerequisites
Alia v0.2.0 supports native Linux with an NVIDIA GPU. It relies on /proc, flock, and the Linux process-start timestamp; Windows, macOS, AMD GPUs, CPU-only use, and WSL2 are not supported. Python 3.12+ is the supported runtime for the process-management behavior tested by this release.
Install the exact Qwen Code version and Hugging Face CLI:
npm install -g @qwen-code/[email protected]
python3 -m pip install -U "huggingface_hub[cli]"
Build a CUDA-enabled llama-server. Commit a0e6dc7 is Alia's minimum supported and measured llama.cpp revision and contains --spec-type draft-mtp:
git clone https://github.com/ggml-org/llama.cpp.git ~/src/llama.cpp
cd ~/src/llama.cpp
git checkout a0e6dc7
cmake -S . -B build -DGGML_CUDA=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j"$(nproc)" --target llama-server
This requires a working NVIDIA driver, a CUDA toolkit supported by llama.cpp, CMake, a C++ compiler, Git, Node.js/npm, and Python/pip. The measured build used CUDA 12.8 on an RTX 3070. Alia looks at ~/src/llama.cpp/build/bin/llama-server; set ALIA_LLAMA_SERVER=/absolute/path/to/llama-server for another tested build. The former Ollama-bundled-binary fallback was removed because its flags and MTP support are not stable public interfaces.
The model repositories are public and normally need no Hugging Face login. If Hugging Face asks for authentication or applies a rate limit, run hf auth login first.
Installation
git clone https://github.com/BEKO2210/alia alia
cd alia
./install.sh
alia doctor
install.sh verifies Python 3.12+, Qwen Code 0.25.1, hf, and llama-server, then creates ~/.local/bin/alia. It stops on any failed filesystem operation. Add that directory to PATH if needed:
export PATH="$HOME/.local/bin:$PATH"
Downloads and disk space
The first start prints the exact hf download command and asks Download now? [y/N]; nothing downloads without confirmation. Allow roughly 10% extra free space beyond the file size:
| Profile/model | Download | Recommended free space | Approx. at 100 Mbit/s |
|---|
| 35B IQ3_XXS default | 14.07 GB | 16 GB | 19 minutes |
| Ornith-1.5 35B-A3B quality | 14.37 GB + template | 16 GB | 20 minutes |
| 9B Q4_K_M fast | 5.7 GB | 7 GB | 8 minutes |
| 35B Q4_K_XL (12–16 GB and 24 GB) | 20.8 GB | 23 GB | 28 minutes |
Actual time depends on Hugging Face and your connection. An interrupted undersized GGUF is rejected on the next start. Downloaded files go under ~/.local/share/alia/models. A documented generic candidate such as ~/models/gguf/Qwen3.5-9B-Q4_K_M.gguf can avoid a second download.
Usage
alia # detect hardware, start server and agent
alia --lang de_DE.UTF-8 # override language for this invocation
alia --continue # continue the latest Qwen session
alia --resume [ID] # resume a Qwen session, optionally by ID
alia --fast # disable thinking for a simple, faster task
alia --wait-gpu 60 # wait for an optional shared GPU lock
alia --auto-edit # automatically allow file edits
alia --yolo # allow all tools; prints a red warning
alia --sandbox # confine tool commands: project writes only, no tool network (needs bwrap)
alia -- -p "Explain main.py" # pass arguments to qwen unchanged
alia web # Web Shell on 127.0.0.1:4170
alia web --port 4317 --no-open --workspace "$PWD"
alia doctor # includes model, hf, disk, and port checks
alia status # server, health, uptime, profile, and model
alia profiles
alia use rtx8gb-qwen35-9b-fast
alia use auto
alia lang de_DE.UTF-8 # persistent German; locale forms work
alia lang en
alia lang auto
alia mcp # list optional MCP servers (browser, search)
alia mcp enable browser # opt in; takes effect with the next session
alia mcp disable search
alia mcp test # start enabled MCP servers and list their tools
alia logs
alia stop
alia --help
alia --version
Language precedence is --lang → ALIA_LANG → configuration → LC_ALL → LC_MESSAGES → LANG → English. Model replies follow the input language unless explicitly requested otherwise.
Alia reads project instructions from QWEN.md, AGENTS.md, and CLAUDE.md. Keep these files short: they are resent with every request, and alia doctor shows their estimated size.
--fast writes chat_template_kwargs.enable_thinking: false; normal runs leave thinking enabled. The default approval mode asks before edits and commands. --auto-edit approves only edits. --yolo approves all tool calls and is only appropriate in a fully trusted workspace.
To coordinate with other GPU jobs, set gpu_lock in ~/.config/alia/config.json or ALIA_GPU_LOCK to a lock-file path. --wait-gpu S bounds how long Alia waits. Alia also always takes its own state lock across reuse checks, startup, and health readiness.
{"gpu_lock": "~/.cache/shared-gpu.lock"}
Runtime data is under ~/.local/state/alia, models under ~/.local/share/alia/models, and preferences under ~/.config/alia/config.json. Qwen uses an isolated Alia QWEN_HOME; host-wide user skills are disabled, while project skills remain available.
Browser and web search (opt-in)
Qwen Code has no browser of its own and its built-in web search needs a cloud key, so Alia can add two optional MCP servers. Both are off by default; alia mcp enable browser|search turns one on, alia mcp disable NAME turns it off, and alia mcp lists them. Changes apply to the next alia or alia web session.
browser — headless Playwright browser (@playwright/mcp 0.0.83): open pages, read text snapshots, click, type, and fill forms. Screenshots and JavaScript evaluation are not exposed. Requires npx (Node.js) and Google Chrome; without Chrome run npx playwright install chromium once. Output goes to ~/.cache/alia/playwright.search — web search and page fetch via DuckDuckGo (duckduckgo-mcp-server 0.7.0), no API key. Requires uvx (uv). It scrapes html.duckduckgo.com, so results can break or be blocked; Alia limits it to 10 searches and 10 page fetches per minute.
Code map (opt-in)
alia mcp enable graph gives the agent a code map of the project: who calls a function, what it calls, and the path between two symbols, with file and line, in a few hundred characters instead of whole files. Before each alia or alia web session Alia indexes the project (or the --workspace of alia web) with graphify 0.9.92 (graphifyy on PyPI, Apache-2.0; Alia is not affiliated with Graphify Labs). Indexing is local tree-sitter parsing of code only: no LLM, no network, no telemetry, and graphify's query log is off. Updates are incremental (about 1 s for Alia's own 700 symbols). The graph lives under ~/.local/state/alia/graphs, not in the project. alia graph [DIR] builds or refreshes it by hand and prints where it is. Requires uvx (uv).
The agent gets five read-only tools: get_node, get_neighbors, shortest_path, god_nodes, graph_stats. graphify's query_graph is left out because it ignores its token budget (8.7K tokens for one question on Alia's repo), and its pull-request tools are left out because they call GitHub. The map helps most in medium and large repositories; in small projects grep is just as cheap. Its effect on agent pass rates is not measured yet. Indexing is skipped in the home directory and /.
Every MCP tool call goes through the normal approval prompt; --yolo approves them without asking. The first session downloads the pinned packages. alia mcp test [NAME] starts the enabled servers (or just NAME) exactly as a session would and lists their tools, waiting up to 90 s for a first download. Alia loads MCP tool schemas upfront (alwaysLoadTools), so the model can call them without a tool_search round trip.
Sandbox (opt-in)
alia --sandbox confines the commands the agent runs with bubblewrap: they may write only inside the project and get no network; the model itself keeps talking to the local server. Host files such as ~/.ssh stay readable, and tools that need a network (for example pip install) fail. Install bwrap (package bubblewrap); alia doctor shows whether it is available. Qwen Code 0.25.1 does not support the sandbox with MCP servers or in alia web, so Alia stops with an error in both cases. Start it from a project directory below your home directory: Qwen Code refuses a workspace that is $HOME itself, lies above it, or overlaps Alia's Qwen state or the Qwen Code installation, and Alia checks this first. Because /rewind cannot restore files in the sandbox, Alia stores uncommitted tracked changes in refs/alia/pre-session before the session (untracked files are not included) and prints the restore command. Details: SECURITY.md.
Bundled profiles
| Profile | Target | Model/download | TG 4K / 32K | PP 4K / 32K | Status |
|---|
rtx8gb-16gb-qwen36-35b | 8 GB VRAM, 16 GB RAM | 35B IQ3_XXS, 14.07 GB | 49.9 / 39.1 | 1,034 / 1,451 | measured, launch config; 32K speed needs free RAM |
rtx8gb-16gb-ornith15-35b-quality | 8 GB VRAM, 16 GB RAM | Ornith-1.5 35B-A3B I-Mini, 14.37 GB + template | — | — | agent tasks 16/16, 248 s mean, 41.8 gen tok/s |
rtx8gb-16gb-qwen36-35b-128k | 8 GB VRAM, 16 GB RAM | same GGUF as the default, ctx 131,072 | — | — | agent tasks 3/3, 44.1 gen tok/s (≈20 % below the default's 54.6) |
rtx8gb-qwen35-9b-fast | 8 GB VRAM, 12 GB RAM | 9B Q4_K_M, 5.7 GB | 66.2 / 57.8 | 2,964 / 2,695 | measured, launch config |
rtx12-16gb-qwen36-35b-q4 | 12–16 GB VRAM, 32 GB RAM | 35B Q4_K_XL, 20.8 GB | 31.8 / 29.1 @28K | 661 / 591 @28K | measured on a Tesla T4 with 53 GB RAM (Colab), launch config, ctx 32K; the runner holds up to 24 GB RAM |
rtx24gb-qwen36-35b-q4 | 20+ GB VRAM, 32 GB RAM | 35B Q4_K_XL, 20.8 GB | 62.4 / 53.2 @28K | 3,027 / 2,744 @28K | measured on an NVIDIA L4 (Colab), launch config, ctx 32K, 22.0 GB VRAM peak; faster cards (RTX 3090/4090) should beat it |
Automatic selection prefers the highest-ranked matching measured profile and warns before using an unmeasured or manually pinned mismatch. Benchmark methodology and limitations are in bench/REPORT.md, raw-data inventory in bench/results/README.md, and independent review in bench/reviews/grok-bench-review.md.
Choosing a profile
The default Qwen3.6 profile is the fast choice: it solved 13/16 frozen agent tasks in about 104 seconds per task. For higher quality, run alia use rtx8gb-16gb-ornith15-35b-quality; Ornith solved 16/16 in about 248 seconds per task, roughly 2.4× slower, and downloads a 14.37 GB GGUF plus its chat template. Run alia use auto to return to automatic selection.
For large tasks, alia use rtx8gb-16gb-qwen36-35b-128k doubles the window: Qwen Code then compacts at about 98K tokens instead of 32.5K, at roughly 20 % lower speed (llama.cpp moves more experts to the CPU to fit the larger KV cache).
Every bundled profile caps llama-server's host-RAM prompt cache at 2,048 MiB, avoiding the swap growth observed with its 8,192 MiB default on a 16 GB machine.
More context with sub-agents
A sub-agent gets its own full window, so splitting a large job is often better than a bigger context. Ask for it in plain words, for example "use a sub-agent to find every caller of parse_config and report file:line". While the sub-agent runs, llama-server keeps the main agent's state in the host-RAM prompt cache instead of the GPU. In a measured run, the main agent resumed after a 10.8K-token sub-agent with 21 newly evaluated tokens (0.4 s) instead of re-reading its 15K-token history (run agent-20261017-211634). A fork sub-agent (subagent_type "fork") inherits the main agent's history and starts almost free; use it when the sub-agent needs the conversation so far.
Adding a profile
Add an object to profiles.json. Use only generic ~/models/... local candidates. Every numeric measured metric needs a metric_sources entry naming its bench/results/*.jsonl run and server context; disclose any binary, context, or flag difference from the launch configuration.
python3 -m json.tool profiles.json >/dev/null
python3 -m unittest discover -s tests -v
./alia profiles
Security
Alia forces llama-server to 127.0.0.1:8090, rejects profile attempts to override host/port, disables llama.cpp's Web UI, and supplies its local API key to both server and Qwen. The server state directory is mode 0700; state, settings, lock, and log files are mode 0600. Stop signals target only the recorded PID after checking its Linux start time. State is retained if the process remains alive after SIGKILL, and Alia never uses pkill.
Loopback is not an isolation boundary between mutually untrusted local accounts. The fixed local API key is visible to sufficiently privileged local processes, and Qwen Web Shell itself has no additional bearer-token gate. Do not expose either port through SSH forwarding, a reverse proxy, containers, or firewall changes. Do not run parallel Alia sessions with different approval modes because they share one settings file. --yolo allows arbitrary tools without confirmation. Ollama unloading talks only to Ollama's loopback API: an unavailable Ollama is ignored, but Alia aborts if discovered models do not unload within 10 seconds.
Showcase
Alia, explained by Alia is a page Alia wrote about its own architecture, running locally on the RTX 3070: it read its own source and built the interactive diagram, the animated request flow and the benchmark section. All prompts are published, including what went wrong.
Development and screenshots
The unit suite is GPU-free and does not start servers or download models:
python3 -m unittest discover -s tests -v
tools/screenshot.sh is developer-only and additionally needs tmux plus a Chrome/Chromium executable. It reads an existing pane; it does not launch Alia or tmux.
Credits and licenses
- Qwen Code, Apache-2.0
- llama.cpp, MIT
- graphify (optional code map, installed from PyPI as
graphifyy), Apache-2.0; "graphify" is a trademark of Graphify Labs, and Alia is not affiliated with it
- Qwen models and GGUF repositories under their respective licenses
See LICENSE and NOTICE. Alia launches external components; it does not redistribute them.
