Installation

Pick your deployment profile.

Solo is the recommended default. All modes share the same vault and MCP stub — they differ in services started, LLM provider, and access pattern.

Get started — v0.5.2 · Linux x86_64

Pre-built binaries

recommended

Three archives — download only what your deployment needs. Linux x86_64. SHA256 and SLSA provenance attestation per archive.

gradatum-server backbone vault

Contains gradatum-server, gradatum-worker, gradatum-admin. Core vault store, job queue, admin CLI.

gradatum-server-v0.5.2-x86_64-unknown-linux-gnu.tar.gz

gradatum-llm LLM layer

Contains gradatum-gateway and gradatum-engine. Router, circuit-breaker, llama-server supervisor. Required for local inference.

gradatum-llm-v0.5.2-x86_64-unknown-linux-gnu.tar.gz

gradatum-mcp agent bridge

Contains gradatum-mcp-stub. MCP bridge for agent clients (Claude Code, Claude Desktop, etc.).

gradatum-mcp-v0.5.2-x86_64-unknown-linux-gnu.tar.gz

Verify integrity

# verify SHA256 (example — server archive)
sha256sum -c SHA256SUMS --ignore-missing

# verify SLSA build provenance (GitHub native)
gh attestation verify \
  gradatum-server-v0.5.2-x86_64-unknown-linux-gnu.tar.gz \
  --repo gradatum/gradatum

crates.io (name reserved)

v1.0 library

Source is open on GitHub (Apache-2.0). The crates.io name is reserved — the full embeddable Rust library ships at v1.0 when the API is stable.

crates.io/crates/gradatum · name reserved · full library at v1.0 · Apache-2.0

Build from source

full control

Clone the repository and compile all workspace crates. Requires recent stable Rust (MSRV).

git clone https://github.com/gradatum/gradatum
cd gradatum && cargo build --release --workspace

github.com/gradatum/gradatum · Apache-2.0 · Rust 2021 · MSRV 1.88+

v0.5.2 · Linux x86_64 · API not stable before v1.0. See docs/DEPLOYMENT.md for the full deployment reference.

Nano L0 Solo ★ L1 Full L1+ Gold L2 Remote L3 Custom L1 Docker L1

Nano L0

Store and retrieve knowledge without an LLM dependency.

Use case — Developer adding persistent RAG memory to an existing CI pipeline or script-driven workflow, without spinning up an LLM service.

gradatum-admin install --level nano

Services: gradatum-server · gradatum-worker
LLM: None (heuristic curator — rule-based, no inference)
MCP access: stub

Solo ★ L1

Full memory-and-gateway stack up and running in one command.

Use case — Developer running gradatum on a personal machine, NAS, or single-board computer for daily agent interactions.

gradatum-admin install

Services: gradatum-server · gradatum-worker · gradatum-gateway
LLM: Local (Ollama / llama.cpp) or cloud (OpenRouter · Anthropic · OpenAI)
MCP access: stub

Full L1+

All optional services enabled — engine, messaging, and vault in one stack.

Use case — Operator running gradatum as a hub for multiple agents with event-driven triggers and local inference via a GGUF model.

gradatum-admin install --level full

Services: gradatum-server · gradatum-worker · gradatum-gateway · gradatum-engine · NATS (if credentials configured)
LLM: Local or cloud; gradatum-engine handles local GGUF inference if provided
MCP access: stub

Gold L2

planned for v0.5

Sovereign remote access — connect from any client without a local stub.

Use case — Operator managing a multi-user deployment where mobile and desktop clients connect directly via OAuth, without installing a local binary.

gradatum-admin install --level gold

Services: gradatum-server (+ /mcp StreamableHTTP) · gradatum-worker · gradatum-gateway · gradatum-engine · NATS · Identity Provider
LLM: Local or cloud
MCP access: stub + Remote OAuth

Remote L3

Connect gradatum-admin to an existing server running on a separate machine.

Use case — Infrastructure operator managing gradatum on a dedicated node or VM, configuring it remotely from a workstation without a local install.

gradatum-admin install --level remote

Services: Remote server via conf.d/ · .env (no local services installed)
LLM: Via /api/v1/config (delegated to the remote server's provider)
MCP access: stub

Custom L1

Pick exactly which components to install — nothing more.

Use case — Operator who needs granular control over installed services, for resource-constrained environments or non-standard deployments.

gradatum-admin install --level custom

Services: Selected interactively (yes/no per component)
LLM: Chosen per wizard step
MCP access: stub

Docker L1

Run the full stack in containers with a generated Compose file.

Use case — Developer or operator preferring containerized deployments for isolation, portability, or use in an existing container infrastructure.

gradatum-admin install --docker --level solo --provider ollama
docker compose up -d

Services: server · worker · gateway (Compose-managed; additional services added based on --level flag)
LLM: Any supported provider, configured via generated .env
MCP access: stub

Supported LLM providers

Provider	Flag	Requirement
Ollama (local)	`--provider ollama`	Ollama installed and running
llama.cpp server	`--provider llamacpp --llm-url URL`	llama.cpp server accessible
OpenRouter	`--provider openrouter --api-key KEY`	OpenRouter API key
Anthropic	`--provider anthropic --api-key KEY`	Anthropic API key
OpenAI	`--provider openai --api-key KEY`	OpenAI API key
Custom OpenAI-compatible	`--provider custom --llm-url URL`	Accessible endpoint
None (Nano mode)	`--level nano`	—

Post-install commands

gradatum-admin init --preset hierarchical --root /var/lib/gradatum

gradatum-admin api-key create --root /var/lib/gradatum --owner mcp-stub
gradatum-admin api-key list   --root /var/lib/gradatum

gradatum-admin jobs list --root /var/lib/gradatum
gradatum-admin jobs dlq  --root /var/lib/gradatum

gradatum-admin vault rename "old title" "new title"  # F-39 stable wikilinks

Example topology — multi-host GPU serving

Single-binary on one box, or scale out: one GPU host serving several models, an app host routing through the gateway with automatic CPU fallback.

  consumers (apps · agents · MCP clients)
               ↓  MCP / HTTP / REST
  ┌──────────────────── app-host (Linux) ───────────────────────┐
  │  gradatum-server ─┐                                         │
  │  gradatum-worker ─┴──────────▶ gradatum-gateway :8436       │
  │                                (router · circuit-breaker)   │
  │                                  │ primary       │ fallback │
  │                                  ▼               ▼          │
  │                            [GPU-HOST]   local CPU fallback  │
  └──────────────────────────────────┼────────────────────────┘
                                   LAN
  ┌──────────────────── gpu-host (Linux) ───────────────────────┐
  │  gradatum-engine · one supervisor binary, one instance/model│
  │   chat :8083 · embed :8432 · small :8082                    │
  │   reason :8081 · vision :8080 (+mmproj)                     │
  │   each instance supervises one llama-server child (loopback) │
  │   GGUF bind-mounted ro · /opt/gradatum/models/              │
  └─────────────────────────────────────────────────────────────┘
  primary → GPU host · fallback → local CPU (circuit-breaker auto)

Full deployment guide and configuration reference: docs/DEPLOYMENT.md.