Node Overview
Host the kernel as a local bridge, a sidecar, or inside your own process, with the stores and keys it needs.
On this page
A signed decision is only as durable as the process that records it. A node is that process: it accepts requests on a transport, holds the key that makes each receipt verifiable, keeps the stores that carry revocations, budgets, and sessions across a restart, and serves nothing until those are ready.
The process that holds the kernel is the trust boundary
In each shape, the process that holds the kernel also holds the signing key and the stores and runs admission. Its dashed outline marks the trust boundary, and its extent is what changes from shape to shape. Architecture.
- admitted route
- The caller reaches the resource through the kernel and adapter. The host closes any other route, including credentials or handles that bypass admission.
- signing key
- Anything that can read the process holding the seed can sign receipts that verify.
- stores
- Two kernels share a revocation view only through a shared store or the trust control plane.
- trust boundary
- Routes around the outlined process are outside both the control and the record.
In Rust · types.rs:11811 lines
/// Optional SQLite database path for durable receipt persistence.
#[arg(long, global = true)]
pub(crate) receipt_db: Option<PathBuf>,
// …
/// Optional file path for a persistent capability-authority seed.
#[arg(long, global = true)]
pub(crate) authority_seed_file: Option<PathBuf>,
// …
/// Optional SQLite database path for durable admission, trust authority, and remote MCP session state.
#[arg(long, global = true)]
pub(crate) session_db: Option<PathBuf>,
The process shape follows from what you deploy. A remote MCP node creates a kernel for each session, a trust-control process hosts shared authority services, and an embedded application runs the kernel inside its own HTTP service. A node names that operational boundary, whatever number of kernels it runs.
The process that holds the kernel holds the key and the stores
Every shape draws the same trust boundary around a different process, so choose the shape by the code you trust to sit inside it.
Embedded, your host links chio-kernel and calls ChioKernel with no network hop, so the whole host process holds the key. As a service, the sidecar listens on 127.0.0.1:9090 by default and alone holds the mounted seed. As a bridge, your MCP client launches chio, which launches the existing server over stdio and refuses to start without its admission and receipt databases; the child server runs outside the boundary with no sandbox of its own.
Anything that can read the process holding the seed can sign receipts that verify, and two kernels share a revocation view only through a shared store or the trust control plane. An operation is governed when it reaches the configured kernel; starting a node intercepts nothing else on its host.
- A local agent's MCP tools.
chio mcp serveover stdio, in Govern a Coding Agent. - Tools for remote clients.
chio mcp serve-httpwith a kernel per session, in Remote MCP Edge. - Your own application. The in-process library, or
ChioLayerin a Tower HTTP service as an embedded node. - Any language over localhost. The sidecar HTTP service beside your application.
- Shared capability, budget, and revocation services.
chio trust serve, in Trust Control Plane. - A2A or ACP clients. An edge library and your own transport, in Listeners & Edges.
A node opens its stores and identity before it accepts a call
One command starts a remote MCP edge with its policy, its two databases, and the identity provider that authenticates callers.
export CHIO_ADMIN_TOKEN="$(openssl rand -hex 32)"
chio --session-db ./edge-session.db --receipt-db ./edge-receipts.db \
mcp serve-http --policy ./policy.yaml --server-id pricing \
--listen 127.0.0.1:8931 \
--auth-jwt-discovery-url https://id.larkfield.example/.well-known/openid-configuration \
--auth-jwt-audience https://pricing.larkfield.example/mcp \
--public-base-url https://pricing.larkfield.example \
-- python mcp_server.pyremote MCP edge listening on http://127.0.0.1:8931/mcp
--policy selects the rules for governed operations. --receipt-db keeps signed call evidence in SQLite, and --session-db keeps durable admission and eligible session state; durable admission needs both. --authority-seed-file keeps the signing identity stable across restarts, and --control-url points the kernel at remote control services instead of local stores.
At boot the node loads its configuration and signing identity, opens its stores, registers its tools, and exposes the transport only after those succeed. On restart it restores eligible sessions under current policy and revocation; session persistence alone recovers no interrupted tool call, which is the job of agent processes.
Read more in Runtime Contract, which retains store ownership, fencing, the boot sequence, and host obligations.
Start with the smallest shape that serves your callers
For one local coding agent, start with the stdio bridge. Your own application can share its process with an embedded kernel. Use the remote edge when clients need an HTTP service with authentication, sessions, and an operational lifecycle.
A node keeps local state without joining a cluster. Point several runtimes at one shared control service when they need a common authority boundary, and read Cluster when that service itself needs peers. Before operating any shape, apply deployment hardening to its stores, signing custody, transports, and execution paths.
Every Node page, by the responsibility it covers
- Node Deployment Model. Runtime Contract states what a kernel-hosting process owns; In-Process Library, Sidecar HTTP Service, Embedded Node, Listeners & Edges, and Remote MCP Edge run each shape.
- Lifecycle & Health. Node Lifecycle drains admitted calls before a stop, Health & Readiness keeps a node in rotation only while it can record, Node Preflight reads the six
chio doctorreports, and Node Upgrade replaces a binary with a restorable copy of its state. - Configuration & Custody. chio.yaml Configuration lists every field and its validation, Secrets & Signing Keys places the seed and rotates trusted issuers, Container Images runs the signed image as a non-root sidecar, and Confidential Node runs inside an attested machine.
- Durable State. Node State on Disk names each file and its writer; Revocation Store, Budget Store, Session Lifecycle, and Approval Store & Channels each keep one kind of decision state, and Retention & Archive bounds the receipt database.
- Guard Runtime. External Guard Adapters bounds waits on outside services, Failure & Recovery brings a degraded guard fleet back, and Guard Supply Chain admits guard code only by verified digest.
- Load & Egress. Backpressure & Limits sizes the load a node accepts, Performance & Tuning finds the bottleneck, and Node Egress Contract bounds the node's own outbound HTTP.
- Audit & Operations. Node Observability joins traces to receipts, SIEM Export delivers every decision at least once, Admin API operates a running edge, and Backup & Restore reopens admission only after explicit checks.