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.5.0
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.
Self-hosted RAG stack for crawl, scrape, search, ingest, query, and ask workflows with Qdrant, TEI embeddings, Chrome rendering, MCP/CLI/REST, and Gemini synthesis.
星數
4
工具
—
可用率
—
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.
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.
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 first-class guided path is npx skills add dinglebear-ai/axon --skill install-axon followed by $install-axon. It respects the release trust boundary below, drives axon setup, and guides deployment/auth/client verification.
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, minisign, install, and (for GPU
synthesis or a configured OpenAI-compatible endpoint) the relevant credentials.
Release installation is fail-closed and is not yet available to the public:
releases through v7.2.23 do not include signatures, and no public release
signing key has been provisioned. Build from reviewed source until a future
release publishes the key fingerprint in SECURITY.md and the key itself at
security/axon-release.minisign.pub. Do not substitute a key downloaded beside
the release artifacts.
After those two trust-anchor files exist, the authenticated flow will be:
The installer requires AXON_UPDATE_MINISIGN_PUBKEY, verifies the
release's detached minisign signature and checksum, and installs axon to
~/.local/bin/axon. Fetch a version-pinned installer from the reviewed release
source instead of piping the mutable main branch directly to a shell.
AXON_UPDATE_MINISIGN_PUBKEY='<trusted release public key>' AXON_INSTALL_DRY_RUN=1 ./install.sh
AXON_UPDATE_MINISIGN_PUBKEY='<trusted release public key>' AXON_INSTALL_PREFIX=/opt/axon ./install.sh
AXON_UPDATE_MINISIGN_PUBKEY='<trusted release public key>' AXON_VERSION=vX.Y.Z ./install.sh
AXON_UPDATE_MINISIGN_PUBKEY='<trusted release public key>' AXON_INSTALL_SKIP_SETUP=1 ./install.sh
AXON_INSTALL_METHOD=build ./install.sh # local cargo build; no release download
Windows
Prerequisites: Windows x86_64, PowerShell 5.1+ or PowerShell Core, minisign,
and the provisioned key described above. Until that key is published, build
from reviewed source instead of using the release installer.
Download the installer and integrity metadata from the versioned release,
validate the checksum, inspect it locally, and then execute that pinned file:
Installs axon.exe to %USERPROFILE%\.local\bin and adds it to the user PATH.
Controls: AXON_INSTALL_DRY_RUN, AXON_INSTALL_PREFIX, AXON_VERSION,
AXON_INSTALL_SKIP_SETUP.
Claude Code plugin
claude plugin install <path-to-this-repo>
The plugin ships no binary and registers no automatic hooks. Install axon
first, then invoke axon setup plugin-hook explicitly for a probe-only
/readyz check. Provisioning uses axon setup or axon compose up on the host.
Deploy
Incus (preferred)
deploy/incus/bootstrap.sh is an idempotent 19-step bootstrap that: launches an
images:debian/bookworm system container under axon-container-profile, applies
GPU passthrough, builds axon from the repo's Dockerfile runtime stage, installs
axon-native.service, brings up Qdrant/TEI/Chrome as nested containers, and
optionally exposes axon's port to the host via an Incus proxy device. A host
axon-incus-bootstrap.service unit re-runs it on host boot.
See deploy/incus/README.md for the split-model
rationale (axon native, infra nested), storage fork (~/.axon-incus), and the
nvidia-procfs fragility note.
~/.axon/ is the canonical home for persistent data on bare-metal (under Incus
it's /mnt/axon-data, mapped from ~/.axon-incus on the host). It is flat — no
nested axon/ subdirectory:
AXON_DATA_DIR defaults to ~/.axon. If you previously used
~/.local/share/axon, axon does not auto-migrate — either mv it to
~/.axon or set AXON_DATA_DIR=~/.local/share/axon to pin the old location.
axon setup init creates ~/.axon, config.toml, and .env idempotently,
filling only missing runtime values and preserving secrets. Focused commands:
.env keeps endpoint URLs (QDRANT_URL, TEI_URL, AXON_CHROME_REMOTE_URL,
AXON_SEARXNG_URL), secrets (AXON_HTTP_TOKEN, TAVILY_API_KEY,
GITHUB_TOKEN, GITLAB_TOKEN, GITEA_TOKEN, Reddit credentials, HF_TOKEN,
OAuth credentials), Docker/runtime bootstrap, and LLM runtime pointers. Optional
ArtifactCandidate delivery uses the paired
AXON_ARTIFACT_CANDIDATE_DEPOT_URL and
AXON_ARTIFACT_CANDIDATE_DEPOT_TOKEN variables. Leave both absent to disable
delivery; if either is present, both must be non-empty and valid or worker/server
startup fails instead of falling back to a disabled sink.
config.toml keeps search/ask tuning, worker and job limits, TEI client
tuning, Qdrant batch sizing, chunking, and logging. See
config.example.toml, .env.example,
and docs/guides/configuration.md for the full
surface.
axon scrape <url> — retained one-page projection: scope=page,
embed=true, limits.max_pages=1, clean content output, no site fanout.
Same pipeline as axon <url> --scope page.
axon map <url> — discover URLs on a site without scraping (embed=false).
axon sessions <export> — index Claude/Codex/Gemini session exports.
Vertical extractors auto-route known URLs (GitHub, PyPI, npm, crates.io, Reddit,
YouTube, …) to structured per-site extractors instead of generic HTML→markdown.
Disable with AXON_ENABLE_VERTICALS=false or the [crawl.verticals] config
section.
Jobs, watches, and cleanup
One durable job model in SQLite owns lifecycle, attempts, stages, events,
heartbeats, artifacts, and provider reservations. Source jobs keep one job id
across resolve, acquire, prepare, embed, publish, graph, and cleanup. Job kinds:
source, extract, watch, map, research, ask, query, retrieve,
memory, graph, prune, provider_probe, reset.
axon <source> --wait true # foreground: enqueue, run workers, block to terminal
axon <source> # detached: enqueue, return job id, exit
axon jobs list # all jobs
axon jobs get <job_id> # status, stages, counts, errors
axon jobs events <job_id> # paged event log
axon jobs stream # live event stream for consumers
axon jobs cancel <job_id>
axon jobs retry <job_id>
axon jobs recover # reclaim stale running jobs (admin)
axon jobs cleanup # remove old terminal jobs
axon jobs worker # run a standalone worker process
Detached work needs workers. A source/extract/watch/retry call returns a
job id when detached. A process must be running with workers for detached jobs
to advance — that's axon serve (or jobs worker). Use --wait true for
foreground completion.
Watches persist a canonical source request and schedule. Each due tick
leases the watch, enqueues one source job, and records the run.
axon watch create <source> --every 1d
axon watch list / get / status / update
axon watch exec <id> # run one tick now
axon watch pause / resume / delete
axon watch history <id>
Cleanup is plan-first.axon-prune owns it; cleanup debt in the source
ledger records work that must be retried or reconciled.
axon prune plan <target> # dry-run reviewable plan
axon prune exec <plan_id> --confirm # destructive execution
axon reset plan # dry-run reset of local stores
axon reset exec --confirm # destructive reset
axon migrate --from <old> --to <new> is the one-time upgrade path that scrolls
an unnamed-mode Qdrant collection and re-upserts it as named-mode (dense + BM42
sparse) for hybrid RRF search.
Hybrid vector search (RRF over dense + BM42 sparse)
axon retrieve <url>
Fetch a source's chunks/documents
axon ask <question>
RAG: retrieve relevant context, then answer with LLM
axon chat <message>
Direct LLM prompt (no retrieval)
axon summarize <url>...
Summarize one or more sources
axon evaluate <question>
RAG vs baseline with independent LLM judge
axon suggest [focus]
Suggest sources to index next
axon train
Collect human preference votes on RAG candidates
axon search <query>
Web search (SearXNG/Tavily), auto-queues source jobs
axon research <query>
Multi-source web research with LLM synthesis
axon extract <url>...
LLM-powered structured extraction (+ lifecycle)
axon brand <url>
Brand identity: colors, fonts, logos, favicon
axon diff <a> <b>
What changed between two URLs
axon endpoints <url>
Discover API endpoints from HTML/JS bundles
axon screenshot <url>
Full-page screenshot
New Qdrant collections are created with named dense + bm42 sparse vectors and
queried with Reciprocal Rank Fusion. Legacy unnamed collections fall back to
dense-only cosine; run axon migrate to upgrade, then point
server.default-collection at the new collection. Tune via [search] and
[retrieval] in config.toml.
Memory
axon memory remember "..." # store a memory record
axon memory list / search / show
axon memory link <a> <b> # relate / supersede
axon memory supersede <old> <new>
axon memory context # recall relevant memories for a query
Memory lives in its own Qdrant collection (axon_memory, or
AXON_MEMORY_COLLECTION) with a decay model: base_score blended from
semantic/confidence/salience/scope/reinforcement, multiplied by a
half-life decay unless pinned. Run axon memory context explicitly for session
recall; the Claude plugin does not register a SessionStart hook.
CLI
The full command registry is generated, not hand-maintained, so it can't
drift. Headline groups:
axon <source> # index a source (the canonical command)
axon scrape / map / sessions
axon query / ask / retrieve / search / research / summarize / evaluate
axon jobs / watch / prune / reset
axon memory / sources / domains / stats / status
axon serve / mcp / doctor / preflight / smoke / config
For the authoritative, always-current full registry — 113 commands across 49
groups with summaries and async/mutates markers — see the generated
docs/reference/cli/commands.md and the
machine-readable docs/reference/cli/commands.json.
Regenerated by cargo xtask schemas cli; cross-checked against the live clap
tree. Per-command flags: axon <cmd> --help.
MCP
Axon supports three MCP tool projections controlled by
AXON_MCP_TOOL_PROJECTION=legacy|atomic|both, or
--mcp-tool-projection on axon mcp / axon serve mcp. The default,
legacy, exposes the compatible axon aggregate with action/subaction
routing. atomic exposes unprefixed canonical operations such as query,
jobs_get, jobs_cancel and uploads_create; their fixed routing fields
are not caller arguments. both publishes both forms, using the same
scope checks, task admission and dispatcher. The dedicated
axon_status_dashboard tool remains unchanged in every mode.
CLI selection overrides AXON_MCP_TOOL_PROJECTION, which overrides the
deprecated AXON_MCP_PROJECTION fallback. See the
MCP reference.
Response modes (response_mode): path (artifact ref), inline, both,
auto_inline — MCP responses never expose a server filesystem path; clients
follow the returned artifact_id. The generated wire contract is
docs/reference/mcp/tool-schema.md.
HTTP auth: static bearer token (AXON_HTTP_TOKEN) or OAuth/lab-auth
(AXON_AUTH_MODE=oauth). Tokenless HTTP is allowed only for loopback
development binds; non-loopback binds require OAuth or a static token. /mcp
and /v1/* share the same auth policy.
HTTP API and surfaces
axon serve starts one Axum HTTP server on AXON_HTTP_HOST:AXON_HTTP_PORT
(default 127.0.0.1:8001) mounting:
/docs — OpenAPI/Swagger UI (OpenAPI JSON at /openapi.json).
The Aurora-styled web control panel (first-run setup, config/stack
inspection, command runner).
OAuth metadata + auth routes when AXON_AUTH_MODE=oauth.
Companion apps (each is a separate release component with its own README under
apps/): Palette (apps/palette-tauri, Tauri desktop app), Android
(apps/android, APK), Chrome extension (apps/chrome-extension), and the
bundled web panel (apps/web).
LLM, search, and adapter configuration
LLM synthesis is selected by AXON_LLM_BACKEND:
Backend
Setting
gemini-headless (default)
Gemini CLI under ~/.gemini (OAuth) or GEMINI_API_KEY
openai-compat
AXON_OPENAI_BASE_URL (API root, not /chat/completions), AXON_SYNTHESIS_OPENAI_MODEL
codex-app-server
codex app-server over stdio in an isolated CODEX_HOME; AXON_SYNTHESIS_CODEX_MODEL
Each backend has AXON_SYNTHESIS_*_MODEL and AXON_CHAT_*_MODEL overrides.
Completion concurrency/timeout are tuning knobs in [providers.llm].
Web search/research uses a self-hosted SearXNG (AXON_SEARXNG_URL) when
configured, falling back to Tavily (TAVILY_API_KEY). Full-content vs.
snippet-only research is providers.search.research-full-content in
config.toml.
Adapter credentials:GITHUB_TOKEN, GITLAB_TOKEN, GITEA_TOKEN,
REDDIT_CLIENT_ID/REDDIT_CLIENT_SECRET, HF_TOKEN. These remain adapter
credentials even though every such target now enters through SourceRequest.
Development
Start with AGENTS.md, the canonical repository instructions.
CLAUDE.md and GEMINI.md are direct relative symlinks to it; scoped guides
use the same arrangement. See contributing
and documentation maintenance for
setup, sources of truth, and verification proportional to the changed files.
cargo build --bin axon # debug
cargo build --release --bin axon # release
cargo check # fast type check
just --list and the Justfile own the current recipe definitions.
just verify is the broad integration gate (including operational and
structural checks); just fix applies formatter/Clippy fixes; just precommit
is the broad staged gate. Use scoped documentation checks for prose-only
changes rather than rebuilding every product surface.
Local dev infra is explicit about Qdrant ownership. just services-up (an alias
for just services-up-local) starts a self-contained Qdrant/TEI/Chrome stack;
just services-up-external-qdrant requires AXON_EXTERNAL_QDRANT_URL and starts
only TEI/Chrome. just services-down removes the local infrastructure services.
Published Qdrant and TEI ports bind to host loopback only; remote access must go
through a separately secured network path rather than an unauthenticated LAN
listener. Production startup also creates the configured external Docker network
idempotently before Compose starts, and production images are pinned by digest.
The dev compose file runs the locally built debug binary from target/debug
inside the axon:dev-runtime image — this is a dev convenience, not the axon
deployment path.
axon setup init accepts only non-secret bootstrap values on its command line.
Set tokens, API keys, and OAuth client secrets through the protected process
environment or the mode-0600 ~/.axon/.env; Axon never places those values in
process arguments.
Module layout: Rust 2018+ file-per-module — no mod.rs. Module roots live
in foo.rs; submodules in foo/bar.rs. Tests live in sibling foo_tests.rs
sidecar files declared via #[cfg(test)] #[path = "foo_tests.rs"] mod tests;
inside foo.rs. See AGENTS.md for the full convention.
Monolith policy: changed .rs files are enforced at CI and via lefthook
pre-commit — file size ≤ 500 lines (hard fail), function size warn at 80 / hard
fail at 120. Exemptions: tests/**, benches/**, config/**, **/config.rs,
and **/*_tests.*. ./scripts/install-git-hooks.sh installs lefthook once.
CLI help contract tests and generated registry drift checks.
Docker image build + GHCR publish workflow.
Compose smoke workflow.
Self-hosted RTX 4070 smoke for Qwen3 TEI cold/warm timing.
Releases are per-component. Three of four (palette, android, chrome) are
release-please-driven; cli is bumped manually with
cargo xtask bump-version patch|minor|major --component cli (release-please can't handle
version.workspace = true; see release-please#2111). Ordinary
release-please-driven app PRs leave version files alone for release-please;
auto-tag selects only the Axon-native CLI and creates its tag and GitHub
Release before dispatching artifact builds. The PR gate is:
cargo xtask check-release-versions --base origin/main --head HEAD --mode pr
See AGENTS.md for the full release pipeline and version-bearing-file rules.
Troubleshooting
Fast checks:
# Bare-metal
axon preflight
axon doctor
systemctl status axon
journalctl -u axon -f
# Incus
incus exec axon -- axon doctor
incus exec axon -- systemctl status axon-native
incus exec axon -- journalctl -u axon-native -f
Incus: /mnt/axon-data/ inside the container ↔ ~/.axon-incus/ on the host.
Host-native CLI commands do not see the Incus deployment's data, and vice
versa — a deliberate, permanent fork (see deploy/incus/README.md).
Common failures:
GPU unavailable: verify nvidia-smi and NVIDIA Container Toolkit on the
TEI host. Under Incus, the nvidia-procfs device may need re-adding after a
container restart (see deploy/incus/README.md).
TEI slow on first boot: model download/cache warmup is the cold path.
LLM unauthenticated: for Gemini, run the Gemini CLI login outside Axon;
for OpenAI-compatible, set AXON_LLM_BACKEND=openai-compat +
AXON_OPENAI_BASE_URL + AXON_SYNTHESIS_OPENAI_MODEL.
Detached jobs never advance: no worker is running — start axon serve
(or axon jobs worker).
Auth failures: make sure Claude/plugin config uses the same token as
AXON_HTTP_TOKEN in ~/.axon/.env.
Documentation
Beyond this README, the live doc tree (under docs/):
Per-crate agent contracts — crates/<name>/src/CLAUDE.md (with
AGENTS.md/GEMINI.md symlinks) for each workspace crate.
Design contract packet — docs/pipeline-unification/
is the historical design record for the source-pipeline unification effort
(issue #298). It's retained as a permanent archive; the live docs above
supersede it for current usage.
Original Dinglebear-authored portions of this project are licensed under AGPL-3.0-only. Separate commercial licensing is available for organizations that need terms outside the AGPL. Third-party material remains under its original license. See LICENSING.md.
A
Axon
dinglebear-ai·4 顆星·
Self-hosted RAG stack for crawl, scrape, search, ingest, query, and ask workflows with Qdrant, TEI embeddings, Chrome rendering, MCP/CLI/REST, and Gemini synthesis.