chio.yaml Configuration

Root Structure

The top-level object is ChioConfig with these sections:

This file reaches a node as a local file and nothing else; Policy Rollout documents why there is no distribution service and how to detect two nodes that ended up with different bytes.

kernel

The required section. It identifies the runtime to the rest of the system through its Ed25519 signing key.

kernel.deadlines

An optional sub-section exposing the runtime hot-path wall-clock budgets. Only the scalar budgets are set from the file; the per-guard and per-server override maps are wired programmatically. Every field is optional, so an absent kernel.deadlines table is valid. Each Some value replaces the matching kernel default, and each omitted field keeps it. The section applies deny_unknown_fields.

adapters[]

Each adapter connects the kernel to one upstream API. At least one adapter is required.

auth

auth:
  type: bearer        # one of: bearer, api_key, cookie, mtls, none
  header: Authorization  # required for bearer and api_key

Validation:

• type must be one of bearer, api_key, cookie, mtls, none.
• When type is bearer or api_key, the header field is required.
• cookie, mtls, and none may omit header.

edges[]

Each edge exposes an adapter through a protocol endpoint.

receipts

logging

telemetry

guards

Globally applied guard configuration. Per-guard configuration (forbidden paths, tool access, egress) belongs in a HushSpec policy; this section sets pipeline-wide knobs.

For details on which guards are configurable through HushSpec, see HushSpec Policy Format. For the runtime pipeline, see Default Pipeline.

wasm_guards[]

Each entry declares a WASM guard module for the pipeline. A module travels with its manifest: guard-manifest.yaml is read from the directory holding the path file.

See Custom WASM Guards for the manifest format, signing, and host imports.

Environment Variable Interpolation

Interpolation runs on the raw YAML before parsing, so every string-typed field is eligible. Two patterns are supported:

${VAR}            # required: error if VAR is unset
${VAR:-default}   # optional: use VAR if set, otherwise the default literal

Variable names match [A-Za-z_][A-Za-z0-9_]*. If multiple required variables are unset, the loader reports them all in a single error so you can fix everything in one pass. The sequence $​{} with no variable name is left as literal text.

kernel:
  signing_key: "${CHIO_SIGNING_KEY}"
  log_level: "${CHIO_LOG_LEVEL:-info}"

adapters:
  - id: petstore
    protocol: openapi
    upstream: "http://${API_HOST}:${API_PORT:-8080}/api"
    auth:
      type: bearer
      header: Authorization

Validation

Validation runs after interpolation and YAML deserialization. All errors collect into a single ConfigError::Validation so the operator can fix everything at once.

• deny_unknown_fields. Every section rejects unknown keys at parse time. Typos like recieipts fail before validation runs.
• At least one adapter. An empty adapter list is rejected.
• Unique adapter IDs. Duplicates are rejected by string comparison. Empty IDs are also rejected.
• Unique edge IDs. Same rule. Empty edge IDs are rejected.
• Reference integrity. Every edge.expose_from must match an adapter id declared in the same file.
• Auth completeness. type values are enumerated; bearer and api_key require a header.
• Non-empty signing key. kernel.signing_key must not be the empty string.
• Logging enums. level and format are checked against their fixed value sets.

Loading from Code

Programmatic callers use the loader entry points in chio-config:

use chio_config::{load_from_file, load_from_str, ChioConfig};

// From a file path:
let config: ChioConfig = load_from_file(Path::new("/etc/chio/chio.yaml"))?;

// From a string (e.g., loaded over the network):
let config: ChioConfig = load_from_str(yaml_text)?;

Both helpers run interpolation, parse with deny_unknown_fields, and run the validation pass before returning. Errors are surfaced as ConfigError with Io, Interpolation, Parse, and Validation variants.

CLI Policy Checks

A policy is a separate file from chio.yaml, and the chio CLI evaluates it through its own commands:

# Spawn an agent under a HushSpec policy.
$ chio run --policy ./policy.yaml -- agent --task my-task

# Evaluate a single tool call against a policy without spawning anything.
$ chio check --policy ./policy.yaml \
    --tool read_file \
    --params '{"path": "/etc/passwd"}' \
    --server '*'

# Scaffold a new project with a sample chio.yaml and policy.
$ chio init my-deployment

chio.yaml itself is checked by chio doctor, which runs six ordered health probes; the sixth parses chio.yaml and checks for two top-level marker keys, version and policy, reporting errors with line and column anchors. chio doctor --fix scaffolds a minimal file containing exactly those keys (version: 1, policy: ./policy.yaml).

Worked Example

A complete chio.yaml for a small deployment: one MCP edge over an OpenAPI adapter, one external guard reachable via the policy compiler, and one custom WASM guard. Secrets are interpolated from the environment.

kernel:
  signing_key: "${CHIO_SIGNING_KEY}"
  receipt_store: "sqlite:///var/lib/chio/receipts.db"
  log_level: "${CHIO_KERNEL_LOG_LEVEL:-info}"

adapters:
  - id: petstore
    protocol: openapi
    upstream: "https://${PETSTORE_HOST}/v1"
    spec: ./specs/petstore.openapi.yaml
    auth:
      type: bearer
      header: Authorization

edges:
  - id: petstore-mcp
    protocol: mcp
    expose_from: petstore

receipts:
  store: "sqlite:///var/lib/chio/receipts.db"
  checkpoint_interval: 200
  retention_days: 365

logging:
  level: "${CHIO_LOG_LEVEL:-info}"
  format: json

telemetry:
  enabled: true
  endpoint: "http://${OTEL_HOST:-localhost}:4317"
  service_name: chio-petstore-edge
  include_parameters: false
  batch_size: 100

guards:
  required:
    - forbidden-path
    - secret-leak
    - patch-integrity
  allow_advisory_promotion: false

wasm_guards:
  - name: tool-denylist
    path: /etc/chio/guards/tool-denylist/tool_denylist_guard.wasm
    fuel_limit: 5000000
    priority: 100

  - name: org-pii-scanner
    path: /etc/chio/guards/pii-scanner/pii_guard.wasm
    fuel_limit: 20000000
    priority: 200
    advisory: false

External provider guards (Bedrock, Azure, Vertex, Safe Browsing, VirusTotal, Snyk) use a distinct policy schema. They are not configured through chio.yaml or a guards: block inside a HushSpec document. Their cloud-guardrail and threat-intel configuration lives on the control-plane external-guard policy schema (the cloud_guardrails and threat_intel fields on GuardPolicyConfig), which the control plane compiles into a pipeline via build_guard_pipeline and build_post_invocation_pipeline (re-exported from chio_control_plane::policy). Within a HushSpec document, threat-intel-driven detection is instead configured at extensions.detection.threat_intel (compiling to the EmbeddingAnomalyGuard). See External Guards for that schema.

Next Steps

• HushSpec Policy Format · the policy file that pairs with chio.yaml
• Custom WASM Guards · author the modules referenced from wasm_guards
• External Guards · cloud content-safety and threat-intel integration
• Wrap an MCP Server · a deployment that uses adapters and protocol endpoints