AX · agent runtime
The kernel owns mechanism. Skills decide behaviour.
AX is a fast, lightweight AI agent for the terminal, written in Rust: a single native binary with sessions, memory, credentials and model config stored locally — no service to sign up for, no remote telemetry.
- v0.3.17
- Rust
- single binary
- local first
- provider-neutral
01 · the loop
One loop. There is no second planner.
Context by budget
The kernel selects context by token budget — never a fixed message count or a fraction of the window. Compression only changes what the model sees; raw history is never deleted.
Tools declare permission
Every tool returns its own capability and safety; permissions are never inferred from a name. Shell and unknown-effect tools hold an exclusive lease; read-only tools declare effects and run concurrently.
Bounded concurrency
Ready independent calls inside the dependency DAG run in parallel — default 4, cap 64, managed by AgentSupervisor.
Checkpoint before advancing
Every message and tool result is written before execution advances. Sessions resume across restarts; completed steps never re-run.
The startup path does as little as possible
AX loads lazily by design: nothing is pulled up at startup that the turn does not need.
- Providers — Connected and authenticated only when needed.
- Skills — Only indexed for routing; bodies load when a route hits.
- MCP servers — Dormant until invoked; the capability catalog is visible without connecting.
- Memory — Retrieved on demand, never on the startup path.
02 · tools
Permissions are declared, not guessed.
Built-ins cover shell, filesystem, search, patch, web and images. Each declares allow, ask or deny for itself — the UI and the runtime share one PermissionStore.
shellfilesystemfind_filesglobpatchsearchwebview_imagebrowserdesktopax run "find the failing test and fix it"03 · capabilities & scopes
Skills, MCP, Agents and Mods share one scope system.
Global
skills, agents, mods, mcp.toml and config.toml under $AX_HOME.
Project
The same definitions under <project>/.ax, overriding global ones. The project UUID lives in .ax/project.json, so moving the project keeps its identity.
Resolution
Global loads first, then project definitions apply, then disabled_global — producing the effective registry. A matching name replaces the whole definition, and disabling never falls back to global.
# skills/<name>/SKILL.md
# agents/<name>.toml
# mods/<name>/mod.json
# mcp.toml
# config.toml# skills/<name>/SKILL.md
# agents/<name>.md
# mods/<name>/mod.json
# mcp.toml
# config.toml
# project.json04 · state & storage
State stays where it belongs.
Where data lives
Persistent data sits under <install-dir>/.ax, with a separate store per project. Opening another directory never moves your data; deleting a workspace never deletes its history.
Database
SQLite holds the session and message repository; each session also has an append-only JSONL event stream that stays authoritative.
Backup
ax export produces an axpack; ax import --dry-run shows conflicts before merging. Credentials and caches are excluded.
Migration
On first launch, legacy ~/.ax and known project stores are copied without deleting the originals. AX_HOME and --data-dir remain explicit overrides.
ax export backup.axpack
ax import backup.axpack --dry-run
ax import backup.axpack05 · sandbox & host access
Know where the boundary is.
Files and terminal, applications and sites, individual actions — these are three separate boundaries with independent grants.
Workspace sandbox
File and terminal tools execute inside a runtime workspace with quotas and TTLs, failing closed.
OS confinement
Native OS-level confinement currently requires Linux. Windows and macOS native sandbox backends are not available, and confined modes fail explicitly instead of allowing through.
Apps and sites
Application, website and action approval are separate from the file/terminal boundary. A host-UI grant does not change the workspace boundary.
Host automation
Native Windows Computer Use is enabled by default and respects explicit disable settings.