Getting started

From an empty machine to a running Covenant daemon and a successful first intent. The whole loop runs locally — no accounts, no API keys required.

Prerequisites

Clone and build

git clone https://github.com/open-covenant/covenant.git
cd covenant
cargo build --workspace --exclude covenant-settlement-program

The first build downloads dependencies and may take a few minutes. Two binaries land under target/debug/:

• covenantd — the daemon. Long-running. Listens on a Unix socket and an HTTP gateway.
• covenant — the command-line client. Speaks to the daemon over the Unix socket.

Configure

Covenant looks for its state under $COVENANT_HOME (default ~/.covenant). The directory is created on first daemon start; you can pre-create it to drop in a configuration file:

mkdir -p ~/.covenant

Configuration lives in ~/.covenant/secrets.toml. A minimal example pointing at a local Ollama instance:

[llm]
provider = "ollama"
model    = "qwen2.5:7b"

[embed]
provider = "ollama"
model    = "nomic-embed-text"

Without this file, Covenant falls back to a mock LLM and a mock search provider — useful for sandboxing, but the research agent will return canned text. See Concepts and Agent manifest for the full configuration surface.

Run the daemon

./target/debug/covenantd

The daemon initialises itself on first run:

• Generates an ed25519 identity at $COVENANT_HOME/identity/local.key with mode 0600.
• Opens a Unix socket at $COVENANT_HOME/sock.
• Binds an HTTP gateway on 127.0.0.1:8421.
• Opens the SQLite memory store at $COVENANT_HOME/memory.db.
• Loads any agent manifests under $COVENANT_HOME/agents/*.toml.

Submit your first intent

From a second terminal:

./target/debug/covenant ping
# → pong

./target/debug/covenant intent "summarise recent work on agent memory"

With no agents registered, the daemon falls back to an echo response and writes a working-tier memory record plus a settlement receipt. Inspect them:

./target/debug/covenant memory recent
./target/debug/covenant receipts recent

Register a real agent

Drop an agent manifest into $COVENANT_HOME/agents/. The repository ships a research agent at agents/research. Build it, then point a manifest at the binary:

cargo build -p research-agent --release

mkdir -p ~/.covenant/agents
cat > ~/.covenant/agents/research.toml <<'EOF'
[agent]
id      = "research@local"
name    = "research"
version = "0.1.0"
runtime = "rust-bin"
entry   = "target/release/research"

[capabilities]
required = ["tool.web_search"]

[resources]
cpu_ms_per_task = 30000
memory_mb       = 512
disk_mb         = 100
network         = "outbound-https-only"
EOF

Restart the daemon, grant the capability, then submit an intent that matches the agent's registered keywords:

./target/debug/covenant capabilities grant tool.web_search
./target/debug/covenant intent "search for recent papers on agent memory"

The daemon routes the intent to research@local, runs the binary as a subprocess, captures the response, writes memory and a receipt, and emits an audit event for the dispatch and the capability check.

Verify the local state

The CLI exposes every primitive's recent state:

covenant memory recent --limit 20
covenant receipts recent --limit 20
covenant capabilities recent
covenant verify --window 100

covenant verify cross-checks the audit log against the memory store, capability ledger, and settlement receipts and reports any drift.

Where to go next

• Concepts — the mental model: intents, agents, capabilities, memory, audit, settlement.
• CLI reference — every subcommand.
• HTTP API — the gateway routes, for browser-facing UIs and third-party tooling.
• Agent manifest — the full agent.toml schema.
• Security model — what Covenant protects, and what it does not.