Kernel Overview
Follow one governed call through the kernel, then find the page for each check, guard, grant, and record it touches.
On this page
The kernel answers one question for every governed call: may this request, under this capability, reach its tool now? It answers before dispatch with allow, deny, or pending approval, and it signs the answer whichever way it goes.
Everything else in this section refines that question. A capability sets the ceiling an agent may act within, operator policy compiles into guards that narrow it, and a receipt binds the decision to the request and the policy that produced it. The same Rust decision core runs inside a hosted node and on its own in a browser, a phone, or a C++ host.
Every governed call takes the same four phases
An edge or host (MCP, HTTP, or an SDK) hands the kernel a tool call request: the operation, its arguments, the caller’s agent id, and the capability token that authorizes it. The native runtime takes the call through four phases in order and calls the decision core three times: to verify the capability, to admit a delegated child’s budget share, and to sign the receipt. Architecture.
- 1native evaluation
kernel::evaluationevaluate_tool_callis the authoritative path. It runs each step in order and answers every outcome, a refusal included, with a signed receipt.
evaluate.rs:13//! What it does NOT do (fenced into `chio-kernel` proper):
//!
//! - Revocation membership lookup (stateful `RevocationStore`).
//! - Budget mutation (stateful `BudgetStore`).
//! - Delegation-chain ancestor inspection against the receipt store.
//! - DPoP proof verification with nonce replay (LRU-backed).
//! - Governed-transaction policy evaluation (pulls in chio-governance).
//! - Payment authorisation (async adapter trait).
//! - Tool dispatch to wrapped servers (async transport).
//! - Receipt persistence / Merkle checkpointing (SQL / IO).
evaluate_tool_call runs its steps, with the stores and tool servers it reaches outside the process. Execution nonces, purchase gates, payment, and trace observers are left out or folded into the phase they belong to.Portable kernelA refusal before dispatch stops the call; a check after it can only withhold
A mediated call presents a signed capability with its request. The hosted kernel checks authority and policy before dispatch, runs configured output checks after the tool returns, and finalizes the receipt. A denial before dispatch means the tool never runs. A block after dispatch withholds the result, and an external effect the tool already performed stands.
The decision core is portable: it evaluates supplied authority and context and returns allow or deny, with no I/O of its own. The hosted runtime adds stateful admission, approval, dispatch, and evidence storage, so calling the portable evaluator alone executes nothing. Core and shell draws that line, and Verdicts and approval covers the three verdicts, of which the hosted approval workflow alone produces pending approval.
A capability binds authority to a subject, scope, lifetime, and constraints; scope matching decides which grant covers a request, and delegation narrows a grant at every hop. The receipt contract fixes what a signed record establishes.
Policy narrows what a grant permits, and never widens it
HushSpec compiles the operator's rules into guards, and the kernel evaluates the installed pipeline. Take an outside buyer's request for pricing.refund on order-77 under a capability that covers it, then add block: ["refund"] to the policy's tool_access guard, beside the forbidden_path and shell_command guards it already enables. chio policy explain walks the request through the compiled guards without admitting it, and names the guard that stops it:
chio policy explain policy.yaml --server pricing --tool refund \
--params '{"order":"order-77"}'call pricing.refund {"order":"order-77"}
1 forbidden-path pass
2 shell-command pass
3 mcp-tool deny refund is blocked by tool_access
stopped at guard 3 of 3; decision denyThe grant still covers refund, and the guard refuses it, so the tool is never dispatched. Input guards run in registration order and stop at the first denial or error (pipelines); advisory guards collect findings without blocking unless a promotion rule matches, and their errors still fail closed (advisory guards, fail-closed semantics); output hooks pass, redact, block, or escalate a returned value. The library default and the runtime profile install different controls.
Read more in Write a Policy, which shows the resulting denial and its receipt in the same project.
Choose a guard by what it inspects
A tool-call rule, a filesystem path rule, and an output redactor see different inputs and act at different stages. The Guard Catalog lists each control's accepted inputs, installation, dependencies, and outcome, and action classification shows which of them a request reaches. External providers and WASM guards extend the catalog across explicit boundaries whose timeout, failure, and confinement settings are part of the deployment contract. After choosing, prove one allowed and one refused operation through the configured application with guard testing.
The kernel enforces only on the paths that reach it
Chio governs calls routed through a supported mediation path, and the deployment keeps agents from bypassing it with direct credentials, another tool connection, or unrestricted host access. Tool confinement depends on the adapter, process isolation, sandbox, and operating-system controls; a request-level path or network guard is not a syscall monitor. The kernel, its keys, its native guards, and its runtime state are trusted, and agent requests and tool output are untrusted inputs. A verified receipt checks the record against an expected signer, which is separate from whether the tool's answer was true. The assurance model holds the complete boundary.
The kernel supplies the decision and evidence contracts that larger systems compose: a node hosts the runtime, a cluster coordinates an operator's fleet, a swarm derives authority across a task graph, and federation establishes standing trust between operators. Each has its own admission and state contract, mapped on the Platform overview; an embedded kernel is enough to begin. The Security area adds retained information flow, verified tool launch, brokered credentials, and authorized response, and the Platform Crate Map locates each part in the source.
Every page in the Kernel section
- Core & Shell and Verdicts & Approval: the decision contract and its three verdicts.
- Pipelines & Composition, Default Pipelines, Requests & Action Classification, The Guard Trait, Guard Evidence, Advisory Guards, Fail-Closed Semantics: how guards are ordered, written, and recorded.
- Capabilities, Scope Matching, Delegation & Attenuation, Receipt Contract: the signed objects a decision reads and writes.
- Guard Catalog, then the families: Filesystem, Network, Shell & Code, Tool Access, Computer Use.
- Rate Limit, Session-Aware, Memory Governance, Approval & HITL: guards that read session state or wait for a person.
- Jailbreak & Injection, Response Sanitization, Data-Layer Guards: guards over content and data.
- HushSpec Policy Format, Policy Patterns & Testing, Policy Compilation, WASM Guard Runtime: writing, compiling, and extending policy.
- Portable Kernel Core and Verified Core Boundary: where the core runs and what is proved about it.