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/agent-os
cargo build --workspace --exclude covenant-settlement-program

The Rust workspace lives under agent-os/; running cargo from the repository root fails because no Cargo.toml sits there. The first build downloads dependencies and may take a few minutes. Three binaries land under agent-os/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.
• covenant-tui: the terminal UI client. Renders intent, memory, audit, capabilities, A2A, chain-receipts, and peer-registry views over the same 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 each agent package under $COVENANT_HOME/agents/, every subdirectory containing an agent.toml; flat *.toml files at the top of agents/ are silently skipped.

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

Each agent is a package directory under $COVENANT_HOME/agents/ containing an agent.toml manifest. The router walks the agents/ directory, picks up each subdirectory's agent.toml, and resolves entry against the package directory. Flat manifest files at the top of agents/ are silently skipped. The repository ships a research agent at agent-os/agents/research; build it and stage the binary alongside an agent.toml so the relative entry path resolves:

cargo build -p research-agent --release

mkdir -p ~/.covenant/agents/research
cp agent-os/target/release/research ~/.covenant/agents/research/

cat > ~/.covenant/agents/research/agent.toml <<'EOF'
[agent]
id      = "research"
name    = "research"
version = "0.1.0"
runtime = "rust-bin"
entry   = "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 the research agent, 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.