axon

Axon

Version: 5.16.0

Axon is a self-hosted RAG stack for crawling, scraping, ingesting, embedding, searching, and asking questions over indexed content. The production release is Docker Compose first: one Axon server container, Qdrant, Hugging Face TEI with Qwen/Qwen3-Embedding-0.6B, and Chrome for JS-heavy pages.

Production Contract

Supported production runtime:

• Docker Compose only.
• Qdrant only for vector storage.
• Hugging Face TEI only for embeddings.
• Qwen/Qwen3-Embedding-0.6B as the production embedding model.
• Gemini CLI is the default LLM synthesis path; OpenAI-compatible endpoints such as llama.cpp are supported when configured with AXON_LLM_BACKEND=openai-compat.
• Web search/research uses a self-hosted SearXNG instance (AXON_SEARXNG_URL) when configured, falling back to Tavily (TAVILY_API_KEY) otherwise.
• Local NVIDIA RTX 4070 target with NVIDIA Container Toolkit.
• CLI and MCP run all actions in-process; deploy the axon serve container only when you need HTTP API access.
• One shared config home: ~/.axon/.env, ~/.axon/config.toml, ~/.axon/jobs.db, ~/.axon/output, ~/.axon/logs, ~/.axon/artifacts, ~/.axon/screenshots, and ~/.axon/tei. Qdrant storage lives on the host running Qdrant; dookie points at tootie by default.

Not supported in the production path:

• systemd deployment of the Axon binary.
• Postgres, Redis, RabbitMQ, AMQP, or external worker services.
• OpenAI-compatible first-run LLM configuration. Configure AXON_LLM_BACKEND=openai-compat manually after setup when using llama.cpp or another OpenAI-compatible /v1/chat/completions endpoint.
• Neo4j or graph retrieval.
• Multiple competing .env or config.toml locations.

Install

Linux

Prerequisites:

• Linux x86_64.
• Docker and Docker Compose.
• NVIDIA driver, nvidia-smi, and NVIDIA Container Toolkit.
• Gemini CLI installed and already authenticated, unless using a configured OpenAI-compatible endpoint for LLM synthesis.
• curl, sha256sum, and install.

One-line installer:

curl -fsSL https://raw.githubusercontent.com/jmagar/axon/main/install.sh | sh

The installer verifies the release checksum, installs the axon binary to ~/.local/bin, then delegates setup to axon setup.

Useful installer controls:

AXON_INSTALL_DRY_RUN=1 ./install.sh
AXON_INSTALL_PREFIX=/opt/axon ./install.sh
AXON_VERSION=vX.Y.Z ./install.sh   # pin a specific release; defaults to latest
AXON_INSTALL_SKIP_SETUP=1 ./install.sh

Windows

Prerequisites:

• Windows x86_64 (PowerShell 5.1+ or PowerShell Core).
• Docker Desktop with the WSL 2 backend (for the full stack).
• NVIDIA driver and NVIDIA Container Toolkit (for GPU acceleration).
• Gemini CLI installed and already authenticated, or a configured OpenAI-compatible endpoint for LLM synthesis.

One-line installer (PowerShell):

irm https://raw.githubusercontent.com/jmagar/axon/main/install.ps1 | iex

The installer verifies the release checksum, installs axon.exe to %USERPROFILE%\.local\bin, adds it to your user PATH, then delegates setup to axon setup.

Useful installer controls:

$env:AXON_INSTALL_DRY_RUN='1'; irm .../install.ps1 | iex
$env:AXON_INSTALL_PREFIX='C:\tools\axon'; irm .../install.ps1 | iex
$env:AXON_VERSION='vX.Y.Z'; irm .../install.ps1 | iex  # pin a version
$env:AXON_INSTALL_SKIP_SETUP='1'; irm .../install.ps1 | iex

Claude Code plugin install:

claude plugin install <path-to-this-repo>

The plugin ships no binary. Install axon first via install.sh, then install the plugin. Its SessionStart hook runs scripts/plugin-setup.sh, which syncs CLAUDE_PLUGIN_OPTION_* settings into process env and delegates to axon setup plugin-hook. That subcommand is probe-only and never deploys: it checks /readyz and exits silently when the stack is up, or prints a one-line run /axon-deploy advisory when it is down. ConfigChange runs the same script so updated plugin settings take effect immediately. Provisioning is the /axon-deploy slash command (or axon setup / axon compose up). No systemd unit is created.

Setup Flow

axon setup is the convenience bootstrap path. It is idempotent and safe to rerun. It:

1. Creates or refreshes ~/.axon.
2. Creates or preserves ~/.axon/config.toml.
3. Creates or preserves ~/.axon/.env, filling only missing runtime values and preserving secrets.
4. Writes Docker Compose assets under ~/.axon/compose.
5. Checks Docker, Docker Compose, nvidia-smi, Gemini CLI auth, and OAuth config when requested.
6. Pulls and starts the Compose stack.
7. Waits for Qdrant, TEI, Chrome, and Axon server health.

Focused commands: