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 — v2.5.0 · Linux x86_64

Pre-built binaries

recommended

Two archives — download only what your deployment needs. Linux x86_64. SHA256 and SLSA provenance attestation per archive. Pre-built archives track the latest published tag (v2.5.0).

gradatum-server backbone vault

Contains gradatum-server, gradatum-worker, gradatum-admin. Core vault store, job queue, admin CLI. Serves MCP natively on /mcp.

gradatum-server-v2.5.0-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-v2.5.0-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-v2.5.0-x86_64-unknown-linux-gnu.tar.gz \
  --repo gradatum/gradatum

crates.io

source release

Source is open on GitHub (Apache-2.0). 28 of the 34 workspace crates are published on crates.io at v2.5.0 — SemVer since v1.0.0, with documented exceptions. The previous minor release renamed a doc-hidden Rust item (ConfigError::PrivacyMaskUnavailable → ConfigError::PrivacyMaskWithoutActivation, in a #[doc(hidden)] module of gradatum-server) — invisible to the public-api surface gate, but still a break for a consumer matching the old variant directly; see the CHANGELOG. v2.5.0 behaviour change: a configured-but-unusable ACL preset now refuses to start the server, instead of silently falling back to deny-all (see the UPGRADING guide). The 2.3.1 → 2.4.0 line made ACL read patterns deny-by-default — see the 2.3.1 → 2.4.0 upgrade guide. Project-map registry operators had breaking changes in v2.2.0 — see the 2.1.0 → 2.2.0 upgrade guide. Moving from 2.0.0 first needs the 2.0.0 → 2.1.0 upgrade guide.

crates.io/crates/gradatum · published (v2.5.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 2024 · MSRV 1.91+

v2.5.0 · Linux x86_64 · SemVer since v1.0.0, with documented exceptions — a doc-hidden Rust API rename in the previous minor release, see the CHANGELOG; v2.5.0 behaviour change: a configured-but-unusable ACL preset now refuses to start the server, see the UPGRADING guide. 28 of the 34 workspace crates published on crates.io; pre-built binary archives track v2.5.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.

sudo bash scripts/install-gradatum-services.sh --build

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.

sudo bash scripts/install-gradatum-services.sh --build --with-gateway

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.

sudo bash scripts/install-gradatum-services.sh --build --with-engine --with-gateway

Services: gradatum-server · gradatum-worker · gradatum-gateway · gradatum-engine · NATS (optional job-completion notifications — external broker, not installed by this script)
LLM: Local or cloud; gradatum-engine handles local GGUF inference if provided
MCP access: stub

Gold L2

planned

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

Use case — Operator managing a multi-user deployment where mobile and desktop clients reach the vault over HTTPS, with authentication fronted by a reverse proxy and an external identity provider.

# the building blocks below are real; the per-user isolation this profile depends on has not shipped
sudo bash scripts/install-gradatum-services.sh --build --with-engine --with-gateway
# + your own reverse proxy / external identity provider in front (not installed by gradatum)

Services: gradatum-server (+ /mcp StreamableHTTP) · gradatum-worker · gradatum-gateway · gradatum-engine · NATS (optional, external) · Reverse proxy + external identity provider (e.g. Traefik + Authentik) — bring your own
LLM: Local or cloud
MCP access: stub + authenticated remote MCP

Remote L3

planned

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.

# no verified mechanism for this in the published source — gradatum-admin has no general
# "point at a remote server" mode; conf.d/ only covers per-engine-instance config files.
# Not available as described.

Services: No verified topology — see command note
LLM: Unverified
MCP access: stub

Custom L1

Compose exactly the services you need from two independent flags.

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

sudo bash scripts/install-gradatum-services.sh --build [--with-engine] [--with-gateway]

Services: gradatum-server + gradatum-worker always; --with-engine and --with-gateway each opt in independently
LLM: Depends on flags chosen — none, local (via --with-engine), or routed (via --with-gateway)
MCP access: stub

Docker L1

Run the full stack in containers with the repo-provided Compose file.

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

git clone https://github.com/gradatum/gradatum.git
cd gradatum && docker compose up -d --build

Services: gradatum-server · gradatum-worker · gradatum-init · gradatum-gateway · gradatum-engine · llama-chat + llama-embed (external llama.cpp containers)
LLM: Bundled llama.cpp containers (chat + embed) — override via environment for another provider
MCP access: stub

Supported LLM providers

Provider	gateway.toml	Requirement
Any OpenAI-compatible endpoint (Ollama, llama.cpp, OpenRouter, self-hosted…)	`[providers.NAME] endpoint = "http://host:port"`	Endpoint reachable, serves `/v1/chat/completions`
Cloud provider requiring a key	`api_key_env = "MY_KEY_ENV_VAR"` (same block)	Env var set with the key
None (no gateway installed)	—	—

Post-install commands

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

gradatum-admin api-key create --root /var/lib/gradatum --owner my-agent
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" --tenant main  # wikilinks stay stable across the rename

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.