Axon

Self-hosted RAG engine in Rust: crawl, scrape, ingest, embed, and query any source, with hybrid retrieval and cited LLM synthesis over MCP, CLI, and REST.

Version: 7.2.6

Every source — a web page, a site, a local checkout, a Git repo, a package, a Reddit subreddit, a YouTube transcript, or an AI session export — enters through one unified pipeline backed by SQLite, Qdrant, Hugging Face TEI, and Chrome/CDP.

Axon runs as a native binary under systemd: an Incus system container is the preferred deployment, bare-metal systemd is a supported alternative. The infrastructure it depends on (Qdrant, TEI, Chrome) typically runs as containers or on external hosts; Axon reaches them by URL.

The unified source pipeline

All source acquisition, refresh, watch, indexing, graph extraction, embedding, publishing, and cleanup flow through one pipeline. CLI, MCP, and REST are thin transport projections over the same SourceRequest DTO.

SourceRequest
  → resolve and route (`axon-route`)
  → acquire (`axon-adapters`)
  → ledger generation + manifest (`axon-ledger`)
  → normalize / parse / prepare (`axon-document`, `axon-parse`, `axon-extract`)
  → embed (`axon-embedding`)
  → publish / query (`axon-vectors`, `axon-retrieval`)
  → graph + cleanup debt (`axon-graph`, `axon-prune`)

One durable job_id crosses every stage — logs, events, ledger rows, graph updates, artifacts, vector payloads, and status all share it. There is no per-source-family pipeline and no per-family job store.

The design contract packet that produced this runtime lives in docs/pipeline-unification/; treat it as the historical design record, not as future work — the clean break is implemented.

Deployment contract

Supported ways to run the axon binary:

• Incus system container (preferred). deploy/incus/bootstrap.sh brings up one Incus system container that runs axon native under a systemd unit (axon-native.service) and Qdrant/TEI/Chrome as nested containers, with GPU passthrough. See deploy/incus/README.md for the profile, storage, and GPU details.
• Bare-metal systemd (supported). Install the binary, drop in deploy/systemd/axon.service, enable it. See deploy/systemd/README.md for the walkthrough.

Both paths run /usr/local/bin/axon serve, which hosts the HTTP API (/v1/*), MCP-over-HTTP (/mcp), the web control panel, and the in-process worker runtime in one process on 127.0.0.1:8001 by default.

Not supported as an axon deployment path: running the axon binary itself in a Docker container as the production deployment. (Container images are still published to GHCR for users who want them, and docker-compose.prod.yaml remains the canonical reference for infra image versions and ports — but the supported production deployments are the two above.)

Not supported at all: Postgres, Redis, RabbitMQ, AMQP, external worker services, Neo4j graph retrieval, or multiple competing .env/config.toml locations. Jobs are stored in SQLite and workers run in the same Tokio runtime as axon serve.

Target hardware: local NVIDIA RTX 4070 with NVIDIA Container Toolkit (for TEI GPU throughput). Axon itself is CPU-only.

Install the binary

The installers fetch a release binary and delegate the rest to axon setup. Deployment (Incus or systemd) is a separate step above.

Linux

Prerequisites: Linux x86_64, curl, sha256sum, install, and (for GPU synthesis or a configured OpenAI-compatible endpoint) the relevant credentials.

One-line installer:

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

The installer verifies the release checksum and installs axon to ~/.local/bin/axon. Useful controls:

AXON_INSTALL_DRY_RUN=1 ./install.sh
AXON_INSTALL_PREFIX=/opt/axon ./install.sh
AXON_VERSION=vX.Y.Z ./install.sh