axon

Axon

Version: 4.2.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 only for LLM operations; the user must already be authenticated.
• Local NVIDIA RTX 4070 target with NVIDIA Container Toolkit.
• Host CLI defaults to client/server mode against http://127.0.0.1:8001.
• One shared config home: ~/.axon/.env, ~/.axon/config.toml, ~/.axon/jobs.db, ~/.axon/output, ~/.axon/logs, ~/.axon/artifacts, ~/.axon/screenshots, ~/.axon/qdrant, and ~/.axon/tei.

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.
• Neo4j or graph retrieval.
• Multiple competing .env or config.toml locations.

Install

Prerequisites:

• Linux x86_64.
• Docker and Docker Compose.
• NVIDIA driver, nvidia-smi, and NVIDIA Container Toolkit.
• Gemini CLI installed and already authenticated.
• 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 before installing the host 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=v1.11.0 ./install.sh
AXON_INSTALL_SKIP_SETUP=1 ./install.sh

Claude Code plugin install:

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

The plugin uses the same Docker setup and ~/.axon files. Its SessionStart hook is a thin adapter around axon setup plugin-hook, which runs preflight first and can fall back to the setup wrapper when local files or services need to be initialized. Use axon setup plugin-hook --no-setup when the hook must only check readiness. It does not create a systemd unit and does not symlink a plugin-cache binary into ~/.local/bin.

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:

axon setup          # init + stack up + preflight
axon setup init     # create ~/.axon, config.toml, .env, and compose assets
axon preflight      # check prerequisites, auth config, and service readiness
axon stack up       # pull/start services, then follow logs until Ctrl-C
axon stack down     # stop services
axon stack restart  # restart services
axon stack rebuild  # rebuild the Axon image and start services
axon smoke          # TEI prewarm + crawl/ask proof
axon setup plugin-hook  # hook-safe preflight path for Claude Code SessionStart
axon setup plugin-hook --no-setup   # preflight only; does not mutate files or services
axon setup targets  # list SSH aliases discovered from ~/.ssh/config (informational)

For local bearer-token operation, no manual env values are required. setup init defaults to loopback MCP HTTP, writes AXON_MCP_AUTH_MODE=bearer, and generates AXON_MCP_HTTP_TOKEN. Optional features need credentials: Gemini auth under ~/.gemini for LLM features, TAVILY_API_KEY for search/research, GITHUB_TOKEN for higher-rate GitHub ingest, and REDDIT_CLIENT_ID plus REDDIT_CLIENT_SECRET for Reddit ingest. OAuth mode also requires AXON_MCP_PUBLIC_URL, AXON_MCP_GOOGLE_CLIENT_ID, AXON_MCP_GOOGLE_CLIENT_SECRET, and AXON_MCP_AUTH_ADMIN_EMAIL.

The warm-path setup goal is under 2 minutes once images and model weights are cached. Cold starts that pull images and model weights can take longer; target-hardware timing still needs to be measured against published release artifacts.

Docker Stack

The production compose file starts:

Service	Purpose	Host bind
axon	HTTP server, web panel, MCP HTTP, action API, in-process workers	127.0.0.1:8001
axon-qdrant	vector storage	127.0.0.1:53333, 127.0.0.1:53334
axon-tei	Qwen3 embeddings through TEI	127.0.0.1:52000
axon-chrome	browser rendering and CDP proxy	127.0.0.1:6000, 127.0.0.1:9222, 127.0.0.1:9223

Start manually: