Architecture

Chio is a capability-scoped trust kernel. Five components enforce a zero-ambient-authority model where every tool invocation must be explicitly authorized, metered, and recorded.

The Five Components

Five components, each with a defined trust boundary.

Agent (Untrusted)

The agent is any LLM-powered process that wants to use tools. Agents are treated as fully untrusted by the kernel. They cannot invoke tools directly. They must present a valid capability token with every request. Agents never have ambient authority; permissions are always explicit and externally granted.

Kernel (Trusted Compute Base)

The kernel is the central mediator and the smallest trusted component in the system. It sits between agents and tool servers, intercepting every invocation request. The kernel:

• 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 every decision

Tool Server (Sandboxed)

Tool servers are the actual implementations that perform work: 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 (Trusted)

The Capability Authority (CA) issues and revokes capability tokens. It defines what an agent is permitted to do: which tools, which arguments, for how long, and with what budget. The CA is typically operated by the system owner or orchestrator, not the agent itself.

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.

Inside the Kernel

The word “kernel” covers more than one thing. Chio splits it into a tiny pure core that is machine-checked in Lean, a thin shell that adapts that core to the real world, and an operational ring that handles I/O, storage, and transport. The trust story hinges on keeping those layers visibly separate.

The trusted compute base, by layer

Three concentric rings. Moving inward, the surface area shrinks and the guarantees get stronger.

• Pure verified core: the 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 and are covered by Lean proofs.
• Kernel shell entry: a thin surface on ChioKernel that assembles inputs and delegates into the verified 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 same kernel code ships in four deployment shapes. The trust model is identical across them; what changes is where the process boundary sits and which wire the agent speaks over.

• 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 surface 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

Every tool invocation follows the same deterministic path through the kernel. There are no shortcuts, no bypass mechanisms, and no exceptions.

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
• Any underwriting agreements are valid and solvent
• The cost is metered and deducted atomically

A tool that prices itself above what the token allows is denied here, before it runs. A tool that misreports its cost gets a signed reconciliation receipt the next time it tries to settle. Finance and security read the same artifact, in the same format, with the same signature.

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": "allow",
  "content_hash": "sha256:d7e8f9a0...",
  "policy_hash": "sha256:b5c6d7e8...",
  "evidence": [
    {"guard": "forbidden-path", "verdict": "allow"},
    {"guard": "path-allowlist", "verdict": "allow"},
    {"guard": "shell-command", "verdict": "allow"},
    {"guard": "egress-allowlist", "verdict": "allow"},
    {"guard": "mcp-tool", "verdict": "allow"},
    {"guard": "secret-leak", "verdict": "allow"},
    {"guard": "patch-integrity", "verdict": "allow"},
    {"guard": "velocity", "verdict": "allow"}
  ],
  "metadata": {
    "financial": {
      "estimated_cost": {"units": 1, "currency": "USD"},
      "actual_cost": {"units": 1, "currency": "USD"}
    }
  },
  "kernel_key": "ed25519:pub:9c7b3f...",
  "signature": "ed25519:e5f6a7b8..."
}

Signing is only the first event in a receipt’s life. After the kernel emits it, the receipt travels through persistence, batched Merkle commitment, optional external anchoring, and finally export to downstream verifiers and SIEMs.

Fail-Closed Semantics

The kernel operates under a strict fail-closed model.

Every way a tool call can fail converges on the same terminal: a signed deny receipt. The diagram below traces the ten known failure modes from the stage that surfaces them down into the shared sink. There is no edge that bypasses signing, and no edge that leads to an unsigned allow.

This shape is the whole point. A misconfigured kernel, a crashed guard, a network partition, or a downed tool server all collapse to the same outcome: the caller gets a signed denial, the receipt log gains one more row, and the auditor can replay exactly what happened. An attacker who disrupts the kernel causes a denial of service, never a privilege escalation.

Zero Ambient Authority

Authority is conferred, not inherited. An agent holds no permissions until a Capability Authority issues a signed, time-bounded, attenuable token granting one specific action. The full framing lives 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: "ed25519:..."

Guard Pipeline Evaluation

The guard pipeline uses a conjunctive model: every enabled guard must allow for the request to proceed. Evaluation runs in a fixed order (cheapest first) and short-circuits on the first deny; a single deny from any guard rejects the entire request. 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 boundaries table describes mechanisms; the diagram below describes the cost of crossing each one. Compromise one boundary and guarantees degrade along a specific axis; compromise none and the guarantees hold as stated.

Key Hierarchy

Chio’s signed artifacts are only as meaningful as the keys that sign them. Production deployments separate five logically distinct roles, each owning a different artifact class and a different 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

• 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