Getting started

This guide installs Covenant from source, brings up the daemon, and dispatches a first intent end-to-end. The full loop runs on the local host without external accounts or credentials.

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"

In the absence of this file, Covenant defaults to a mock LLM and a mock search provider; the research agent will return placeholder text under that configuration. Refer to 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 a first intent

From a second terminal session:

./target/debug/covenant ping
# → pong

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

With no agents registered, the daemon returns a deterministic echo response and persists a working-tier memory record alongside a settlement receipt. Inspect both:

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

Register an agent

Place an agent manifest under $COVENANT_HOME/agents/. The repository includes a research agent at agents/research. Build the agent and create a manifest pointing at the resulting 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 required capability, and 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, executes the binary as a subprocess, captures the response, persists the memory record and settlement receipt, and emits audit events for both the dispatch and the capability check.

Verify local state

Each primitive's recent state is queryable through the CLI:

covenant memory recent --limit 20
covenant chain status --json
covenant receipts recent --limit 20 --json
covenant chain flush-receipts --limit 20 --json
covenant chain receipt-batches --limit 20 --json
covenant capabilities recent --limit 20 --json
covenant capabilities purge --older-than-ms 2592000000 --json
covenant verify --window 100 --json

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

Further reading

• Concepts — data model: intents, agents, capabilities, memory, audit, and settlement.
• CLI reference — complete subcommand reference.
• HTTP API — gateway routes for browser-facing UIs and third-party integrations.
• Agent manifest — full agent.toml schema.
• Security model — trust boundaries and operator responsibilities.