Docs

Short documents, real behaviour.

The full, versioned documentation lives in the repositories — ax/docs and axcrew/docs. This is an essentials index in the same voice: every entry maps to something the code actually does.

01

Overview

AX is an agent runtime kernel — not a chat personality layer. One model → tool → model loop, checkpointed sessions, and a narrow contract for capabilities. AXCrew is the control plane that schedules work across AX devices and streams what happens, without touching agent state.

02

Install

One command, verified against SHA256SUMS. Installers fetch the latest GitHub release, verify the archive, and install a single binary. Pin a tag with AX_VERSION or a directory with AX_INSTALL_DIR.

install
curl -fsSL https://raw.githubusercontent.com/Axium-Labs/AX/main/scripts/install.sh | sh
03

Model response handling

Chat Completions and Responses adapters retain reasoning state for the matching provider and model. Explicit stream errors and missing completion boundaries fail instead of accepting partial output as success. Unfinished tool calls are withheld from execution; declared token limits use the existing continuation path.

04

Runtime

The kernel owns context selection by token budget (never fixed message counts), capacity-aware compaction, checkpointed tool rounds, and a dependency DAG that runs ready independent calls with bounded concurrency (default 4, cap 64). Long tasks run in the same loop — there is no separate planner.

05

Tools & permissions

Built-ins: shell, filesystem, find_files/glob, patch, search, web, view_image. Every tool declares its own permission — allow / ask / deny per capability — through one PermissionStore shared by UI and runtime. Shell and unknown-effect tools hold an exclusive lease; read-only tools declare effects and run concurrently.

tools
ax run "find the failing test and fix it"
06

Browser preview & control

Crew provides native browser tabs in the conversation sidebar. Local Windows AX uses an authenticated loopback bridge to inspect and interact with those pages, enforcing AX website permissions and controlled-page network protection. Other desktop platforms currently support user preview without Agent control. Remote AX tasks use their own runtime; standalone browser automation requires Node and Playwright.

07

Skills

Skills are SKILL.md packages in $AX_HOME/skills or <project>/.ax/skills. Routing is lexical and language-independent; bodies and resources load only when a route hits. Enable/disable is deterministic, scoped, and never needs a model call.

08

MCP

AX implements stdio, Streamable HTTP and WebSocket transports. Servers stay dormant until a proxy tool is invoked; the capability catalog is visible without connecting. Remote tools become ordinary tools named mcp__server__tool.

mcp
ax mcp tools <server>
09

Memory

Three scopes — Global, Project, Session — in SQLite with append-only JSONL history. Retrieval filters by owner, recalls at most 32 candidates, reranks lightly and injects bounded summaries. No embeddings, no vector store, no extra model call.

10

Subagents

The main model decides when delegation helps research, writing, analysis or coding. Ordinary subagents and queue children share depth, concurrency and inherited permission ceilings. AXCrew’s Plugins → Agents page controls global/project limits: depth 0 disables local delegation, 1 permits direct children, and larger depths permit nesting. Data inventories alone do not start children.

11

Sandbox

File and terminal tools use the workspace sandbox; native OS confinement currently requires Linux. Application/site access and action approvals are separate from the file/terminal boundary. Windows/macOS native sandbox backends remain unavailable.

12

Providers

Provider-neutral. OpenAI-compatible endpoints (DeepSeek, Groq, Mistral, OpenRouter, xAI, Kimi, …), OpenAI Responses, native Anthropic/Gemini/Vertex/Bedrock/Radius adapters, Codex device-flow OAuth, WorkBuddy account login. Implement ModelProvider to add a local model — no loop changes.

providers
DEEPSEEK_API_KEY=… ax --provider deepseek --model deepseek-chat
13

ACP adapter

ax acp speaks Agent Client Protocol v1 over stdio: initialize, session/new, load, resume, prompt, cancel, plus read-only _ax/status, _ax/models, _ax/tools, _ax/capabilities and scopedCapabilities. One JSON-RPC object per line.

acp
ax acp
14

AXCrew

A Rust control plane with a desktop client (Tauri 2 + React) and an Android client. Schedules deterministic task DAGs across paired AX devices, maintains device identity, brokers approvals, and streams live CrewEvent JSON. AX keeps history, memory, tools and credentials.

crew
axcrew up
ax crew pair <code> --gateway https://crew.example.com
15

CLI reference

Everything is reachable from one binary. Sessions resume across restarts; goals can be suspended, resumed, superseded or cancelled without losing checkpointed work. /system shows measured CPU, memory and NVIDIA GPU usage on demand.

One topic per file, cross-referenced instead of duplicated. Architecture decisions with lasting consequences are recorded in ax/docs/adr.

ax/docs  ·  axcrew/docs