Kleos

vector-store dependency (LanceDB); libpcsclite-dev is for the PIV/YubiKey

TUI installer (terminal) -- linux-x64

./kleos-install

GUI installer (desktop) -- linux-x64

./kleos-install-gui

On Windows, install with the PowerShell script (it fetches the windows-x64 binaries from the latest release):

Other platforms build from source (below).

The installer walks you through component selection, server configuration, embedding provider setup, security key generation, and optional systemd/launchd service registration. Choose a profile (Server, Agent Host, Full, Custom) or pick individual components.

**Or build from source:**

System packages (Debian/Ubuntu): protobuf-compiler builds the proto-based

smartcard path. Both are pulled in by the default workspace build.

sudo apt install protobuf-compiler libpcsclite-dev

cargo build --release -p kleos-server -p kleos-cli KLEOS_BOOTSTRAP_SECRET=pick-a-secret \ KLEOS_SESSION_KEY=$(openssl rand -hex 32) \ ./target/release/kleos-server

`KLEOS_SESSION_KEY` is a 32-byte hex HMAC key for session tokens. Leave it
unset for a quick local try and the server generates an ephemeral one at
startup (with a warning) -- fine for one run, but sessions won't survive a
restart. Set it explicitly for anything you plan to keep running.

Server starts on `127.0.0.1:4200`. In another terminal:

**First run:** with default features, the server background-downloads its local
ML models from Hugging Face the first time it starts -- a bge-m3 embedding model
and a cross-encoder reranker (quantized ONNX by default; several hundred MB
each, up to ~2.3 GiB if you switch the embedder to the FP32 variant). They land
under `<data dir>/engram/models/<model-name>` (e.g.
`~/.local/share/engram/models/bge-m3` on Linux), and future restarts skip the
download once the files are present. For air-gapped or pre-staged deployments,
set `KLEOS_EMBEDDING_OFFLINE_ONLY=1` to make a missing model file a hard error
instead of a network fetch, and pre-stage the files yourself (`KLEOS_EMBEDDING_MODEL_DIR`
/ `KLEOS_RERANKER_MODEL_DIR` control where they're expected). Point `KLEOS_EMBEDDING_URL`
and/or `KLEOS_RERANKER_URL` (with `KLEOS_RERANKER_BACKEND=http`) at a remote
provider instead, and the server skips its local download and ONNX runtime
entirely for that model. To leave the whole local inference stack out of the
binary, build with `--no-default-features` (the default-on `ml` cargo feature
gates the ONNX/LanceDB stack; retrieval degrades to FTS + sqlite-vec and the
remote providers above).

**Bootstrap your admin key (one-time):**

**Store a memory:**

**Search by meaning:**

For Claude Code hooks, encryption setup, the session sidecar, and client SDKs, see the Getting Started guide.

</details>

<details> <summary><strong>For developers: integration and architecture</strong></summary>

<br>

Building from source

```bash

Install profiles

The installer (kleos-install or kleos-install-gui) supports four profiles:

</details>

---

Agent-host (CLI tools, credential daemon, supervisor)

cargo build --release -p kleos-cli -p kleos-sh -p kleos-cred -p kleos-credd \ -p agent-forge -p eidolon-supervisor

Claude Code integration

The hooks/ bundle is under maintenance and not currently shipped. For session-start (and other lifecycle) integration today, call the kleos-cli hook subcommands directly from your own hook scripts -- kleos-cli hook session-start, user-prompt, stop, pre-tool, post-tool, and post-bash are supported and documented in docs/KLEOS_OPERATIONS_MANUAL.md. The mandatory-rules text these hooks inject is operator-configurable via the KLEOS_MANDATORY_RULES environment variable on the server. A new hooks bundle will ship once the surface stabilises.