System architecture

Covenant is a single long-running daemon (covenantd) plus a thin set of clients (the CLI, the TUI, the web UI, third-party tooling over HTTP) and a number of agent processes. The daemon is the only component that holds state; everything else is replaceable.

Component map

┌──────────────────────────────────────────────────────────────┐
│                          covenantd                           │
│ ┌──────────┐  ┌──────────┐  ┌────────────┐  ┌────────────┐  │
│ │  IPC     │  │   HTTP   │  │   MCP      │  │   A2A      │  │
│ │  socket  │  │  gateway │  │ adapter    │  │ adapter    │  │
│ └────┬─────┘  └────┬─────┘  └─────┬──────┘  └─────┬──────┘  │
│      │             │              │               │          │
│      ▼             ▼              ▼               ▼          │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │                    Server::respond                       │ │
│ │ (intent dispatch, capability checks, audit, ignore set)  │ │
│ └────────┬─────────┬─────────┬─────────┬─────────┬─────────┘ │
│          │         │         │         │         │            │
│          ▼         ▼         ▼         ▼         ▼            │
│      ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐        │
│      │Router│ │Runtime│ │Memory│ │ Audit│ │Settlement│        │
│      └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───────┘        │
│         │        │        │        │        │                │
└─────────┼────────┼────────┼────────┼────────┼────────────────┘
          │        │        │        │        │
          ▼        ▼        ▼        ▼        ▼
       cards    spawned  SQLite  JSONL    JSONL     local
       on disk  processes  +    audit/   receipts  settlement
                          embeds events           scaffold

Process model

covenantdruns as a single process per machine, owned by the operator's user account. It owns:

• a Unix socket at $COVENANT_HOME/sock for local clients,
• an HTTP listener on 127.0.0.1:8421 for browser- facing UIs and third-party tooling (loopback only),
• the SQLite memory database at $COVENANT_HOME/memory.db,
• append-only JSONL stores under $COVENANT_HOME for audit, capabilities, peers, receipts, budget, and a2a,
• the local ed25519 identity key.

Subprocess-style agents (rust-bin, python3, node) run as child processes spawned on demand when an intent is dispatched. The runtime registers each subprocess in an in-memory tracker, walks the tracker on a periodic projection tick, and preempts via SIGTERM with a grace window before SIGKILL whenever project_overshoot flags an in-flight process as on track to exceed its remaining credit budget. The wall-clock kill at the agent-declared cpu_ms_per_task remains as the final backstop. hermes-runtime agents are not subprocesses; the daemon delegates the intent to a configured Hermes HTTP endpoint and treats the response as the agent result. In either model, agents have no direct access to the daemon's state; every interaction goes through the daemon.

Request lifecycle

1. A client (CLI, TUI, web UI, third-party caller) sends a SubmitIntent request over the Unix socket or HTTP.
2. The daemon checks the intent text against the configured ignore set; matches are short-circuited with anIntentIgnored audit event and skipped.
3. The router scores the intent against registered agent capability cards via keyword overlap and selects the best match (or falls back to an echo response).
4. The daemon runs a capability check for the matched agent's required actions. The check writes a CapabilityCheck audit event regardless of outcome. A failed check rejects the dispatch with Response::Error.
5. On success, the runtime spawns the agent, sends the intent on stdin, reads the result on stdout, and enforces the budget via both the wall-clock kill at cpu_ms_per_task and the periodic projection tick that preempts via SIGTERM/grace/SIGKILL on projected overshoot.
6. The daemon writes a working-tier MemoryRecord (with an embedding vector if an embedder is configured), a SettlementReceipt for the resources consumed, and an IntentDispatched audit event.
7. The client receives an IntentResult with the intent UUID, the result text, sources, and (when applicable) the receipt.

State on disk

Everything Covenant remembers about its operations sits under $COVENANT_HOME. Default location is ~/.covenant; override with the COVENANT_HOME environment variable.

Crate layout

The daemon is composed from a number of small Rust crates, each owning one primitive. Each crate exposes a trait + at least two implementations (one for production, one in-memory for tests), which keeps the daemon's wiring straightforward and the test suite fast.

Settlement scaffold

Covenant records local settlement receipts today. The repository also contains an experimental Anchor program for the future Solana settlement path described in Settlement. Credit minting, burn reconciliation, oracle integration, and provider payout flows are tracked as protocol hardening work.

The design boundary is deliberate: local receipts make resource accounting inspectable while the on-chain authority surface remains a hardening target.

Position in the stack

Covenant operates between the host operating system and user-facing agentic applications. It does not host language models and does not prescribe agent reasoning strategies. Custom agents, framework-built agents, and end-to-end fine-tuned agents integrate against the same primitive set, so that identity, permissions, memory, communication, and settlement are provided as shared host-level services rather than reimplemented per application.