Architecture

The Five Components

Chio governs the execution stage of autonomous commerce, where an agent's mandate determines which action the protocol permits. Autonomous Commerce traces the broader process. This page describes the five components and their trust boundaries.

Agent (Untrusted)

An agent is an LLM-powered process that uses tools. The kernel treats agents as untrusted. An agent presents a valid capability token with each request; it has no ambient authority.

Kernel (Trusted Compute Base)

The kernel is the trusted mediator between agents and tool servers. It processes each invocation request and:

• Validates capability tokens (signature, expiry, scope)
• Runs the guard pipeline against the request
• Enforces economic constraints (budgets, metering)
• Dispatches allowed calls to the appropriate tool server
• Signs and commits a receipt for each mediated decision

Tool Server (Sandboxed)

Tool servers perform work such as reading files, querying databases, calling APIs. They can be native Chio tool servers or existing MCP servers wrapped by the Chio proxy. Tool servers are sandboxed: they only receive calls that have already passed the kernel's validation and guard pipeline.

Capability Authority

The Capability Authority issues and revokes capability tokens: it defines the tools, arguments, duration, and budget available to an agent. The trust control plane handles issuance and revocation alongside identity, credentials, federation, and governance. A federated issuer mints a scoped token with chio trust federated-issue. The system owner or orchestrator typically operates the authority. The kernel enforces the tokens it signs and is the trusted compute base.

Receipt Log (Integrity-Verified)

The receipt log is an append-only store of signed receipts. Each receipt records a single kernel decision (allow or deny), including the full request, the guard evaluation results, timing, and a cryptographic signature. Receipts are cryptographically signed, making tampering detectable.

System groups

The five components enforce a call. The wider system groups work around the kernel. The runtime kernel is the trusted mediator. The trust group handles identity, credentials, federation, governance, capability issuance, and revocation. The economy group handles metering, budgets, and settlement. These groups use kernel-signed receipts as their records of decisions.

The workspace contains more than 100 crates in eleven groups:

Inside the Kernel

This page distinguishes a pure core, a shell that adapts external inputs, and operational code for I/O, storage, and transport. Lean theorem checking covers stated properties of a bounded model of selected pure-core symbols; it does not cover the full runtime.

Trusted computing base and proof boundary

The diagram separates the core, shell entry, and operational code. The inner components have a smaller trusted code base.

• Pure core: selected pure symbols in chio-kernel-core shown in the Lean map below (capability verification, grant resolution, evaluation, receipt signing, and scope subset) have no I/O. The theorem families below cover their stated properties over the claim-registry bounded model.
• Kernel shell entry: an interface on ChioKernel that assembles inputs and delegates into the pure core.
• Operational shell: everything else, transport, dispatch, persistence, budget mutation, revocation. A fault here can deny service; it cannot silently widen authority.

Where the kernel actually runs

The kernel ships in four deployment configurations. The trust model is the same; the process boundary and transport differ.

• Embedded library: link chio-kernel-core directly into the agent. Minimum footprint, but the agent owns the signing key. Good for single-tenant local deployments.
• Native sidecar: run the kernel as a separate process, agents speak length-prefixed canonical JSON over a Unix socket or TCP. Process-level isolation between agent and kernel.
• Hosted MCP edge: chio mcp serve-http exposes an MCP-compatible HTTP interface with remote session lifecycle and a control-plane API. Tenanted deployments.
• Envoy ext_authz: run the kernel as an external authorization service for any HTTP API that Envoy fronts. Protects arbitrary upstream services with header mutations and structured verdicts.

Message Flow

A tool invocation follows the kernel's deterministic evaluation path.

The kernel evaluation stages in detail:

Stage 1: Token Validation

The kernel extracts the capability token from the request and validates:

• Signature: the token was issued by a recognized Capability Authority
• Expiry: the token has not expired (time-bounded by design)
• Scope: the requested tool and arguments fall within the token's declared scope
• Revocation: the token has not been revoked by the CA

If any check fails, the request is immediately denied. No further processing occurs.

Stage 2: Guard Pipeline

If the token is valid, the request enters the guard pipeline. The pipeline is composed of composable guard families covering filesystem, shell, network egress, tool access, secrets, patch integrity, prompt safety, threat intel, rate limiting, and agent-surface controls (computer use, browser automation, code execution, remote desktop):

Guards are composable and independent. Each guard receives the full request context and returns an allow or deny verdict. The pipeline uses a conjunctive model: all guards must allow for the request to proceed.

The map below shows which Rust symbols each theorem constrains. The boundary is deliberately narrow: revocation lookups, budget mutation, DPoP verification, and tool dispatch stay in the operational shell until a later formal phase pulls them in.

Stage 3: Economic Check

After the guard pipeline, the kernel evaluates economic constraints. Each tool call has an associated cost, and the capability token carries a budget. The kernel verifies:

• The token's remaining budget can cover the estimated cost
• A durable pre-execution hold is placed before the tool runs, so an over-budget call is denied before anything executes
• The cost is metered and reconciled against that hold

A tool that prices itself above the token's allowance is denied before it runs. A tool that misreports its cost receives a signed reconciliation receipt when it next settles. Finance and security use the same signed receipt format.

Stage 4: Receipt Signing

Regardless of outcome, the kernel produces a signed receipt. The receipt includes the original request, the decision (allow/deny), which guards passed or failed, timing information, and economic data. The receipt is signed with the kernel's private key and appended to the receipt log. The receipt outlives the kernel that signed it: a verifier years later needs only the public key and the canonical bytes.

{
  "id": "rcpt_a1b2c3d4e5f6",
  "timestamp": 1744537862,
  "capability_id": "cap_7f3a...e91d",
  "tool_server": "srv-files",
  "tool_name": "read_file",
  "action": {
    "parameters": {"path": "./workspace/README.md"},
    "parameter_hash": "sha256:a1b2c3d4..."
  },
  "decision": {"verdict": "allow"},
  "content_hash": "sha256:d7e8f9a0...",
  "policy_hash": "sha256:b5c6d7e8...",
  "evidence": [
    {"guard_name": "forbidden-path", "verdict": true},
    {"guard_name": "path-allowlist", "verdict": true},
    {"guard_name": "shell-command", "verdict": true},
    {"guard_name": "egress-allowlist", "verdict": true},
    {"guard_name": "mcp-tool", "verdict": true},
    {"guard_name": "secret-leak", "verdict": true},
    {"guard_name": "patch-integrity", "verdict": true},
    {"guard_name": "velocity", "verdict": true}
  ],
  "metadata": {
    "financial": {
      "grant_index": 0,
      "cost_charged": 1,
      "currency": "USD",
      "budget_remaining": 199,
      "budget_total": 200,
      "delegation_depth": 0,
      "root_budget_holder": "agent-research-bot",
      "settlement_status": "pending"
    }
  },
  "kernel_key": "9c7b3f1a2e8d4c6b...",
  "signature": "e5f6a7b8c9d0e1f2..."
}

After signing, the kernel persists the receipt, groups receipts into a Merkle checkpoint, can anchor it externally, and exports it to verifiers and SIEMs.

Fail-Closed Semantics

The kernel denies a call when an evaluation stage cannot establish an allow verdict.

The known failure modes converge on a signed deny receipt. The diagram traces ten modes from their evaluation stage to that result. The modeled paths do not bypass signing or produce an unsigned allow.

A misconfigured kernel, crashed guard, network partition, or unavailable tool server produces a signed denial. The receipt log records the event for replay. Within this model, disruption causes a denial of service rather than a privilege escalation.

Zero Ambient Authority

A Capability Authority grants authority through signed, time-bounded, attenuable tokens. The full model is described in the Trust Model; in the wire format, that token looks like this:

# An agent with this capability can ONLY:
#   - Call read_file on server srv-files
#   - For the next 30 minutes
#   - Up to 50 invocations
#   - With a max cost of $0.10 per invocation

capability:
  id: cap_7f3a...e91d
  issuer: ca-prod-01
  subject: agent-research-bot
  issued_at: 1744536000
  expires_at: 1744537800
  scope:
    grants:
      - server_id: srv-files
        tool_name: read_file
        operations: [invoke]
        max_invocations: 50
        max_cost_per_invocation:
          units: 10
          currency: USD
  delegation_chain: []
  signature: "e5f6a7b8c9d0e1f2..."

Guard Pipeline Evaluation

The guard pipeline uses a conjunctive model: enabled guards must allow a request for it to proceed. Evaluation runs in a fixed order (cheapest first) and short-circuits on the first deny. For the per-guard reference, the authoring model, and custom-guard composition, see Guards.

Component Boundaries

The trust model depends on strict boundaries between components:

What an adversary would have to do

The table names the mechanisms. The diagram shows the effect of compromising each boundary and the guarantees affected.

Key Hierarchy

Signed records depend on the keys that sign them. Production deployments separate five logical roles, each with a record type and rotation domain.

Local development can collapse the three signer roles onto a single Ed25519 keypair, and the examples throughout these docs do. Production and hosted profiles separate them so a compromised kernel signer cannot mint capabilities, a compromised capability authority cannot forge receipts, and a compromised checkpoint publisher cannot do either. Rotation is per-domain: rotating the kernel signer does not invalidate outstanding capabilities, and rotating the capability authority does not invalidate past receipts.

Next Steps

• Autonomous Commerce: the autonomous-commerce process the kernel governs
• Capabilities: deep dive into token structure, delegation, and revocation
• Guards: detailed reference for every guard in the pipeline
• Receipts: cryptographic receipt format and verification
• Economics: budgets, metering, settlement, and underwriting