chio.yaml Configuration

Top-level sections

The top-level object is ChioConfig. Only kernel and adapters are required.

kernel

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

signing_key

receipt_store

log_level

deadlines

kernel.deadlines

The file sets the scalar budgets; the per-guard and per-server override maps are set programmatically. Every field is optional. Each value present 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.

adapters[].auth

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

• type is one of bearer, api_key, cookie, mtls, none.
• bearer and api_key require header.
• cookie, mtls, and none may omit header.

edges[]

Each edge exposes one adapter through a protocol endpoint.

receipts

logging

telemetry

guards

Pipeline-wide guard settings. Per-guard rules such as forbidden paths, tool access, and egress belong in a HushSpec policy; the runtime order is on Default Pipelines.

Those two fields are the base runtime schema. Guard crates read their own tuning blocks under guards: internal_network.extra_blocked_hosts, agent_velocity.max_requests_per_agent, data_flow, behavioral_sequence, response_sanitization.min_level and action, and the advisory settings for anomaly, data transfer, and promotion rules. Each guard's page documents its block, for example Network Guards for internal_network and Filesystem Guards for the path guards.

External provider guards (Bedrock, Azure, Vertex, Safe Browsing, VirusTotal, Snyk) are configured on the control plane's external-guard policy schema: the cloud_guardrails and threat_intel fields on GuardPolicyConfig. The control plane compiles them into pipelines with build_guard_pipeline and build_post_invocation_pipeline, re-exported from chio_control_plane::policy. Inside a HushSpec document, threat-intel detection sits at extensions.detection.threat_intel and compiles to the EmbeddingAnomalyGuard. External Guards documents that schema.

wasm_guards[]

Each entry declares one WASM guard module for the pipeline. The loader reads the module's guard-manifest.yaml from the directory that holds the path file. Custom WASM Guards covers the manifest format, signing, and host imports.

Environment variable interpolation

Interpolation runs on the raw YAML before parsing, so every string-typed field can take a variable. Two patterns are recognized.

${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_]*. When several required variables are unset, the loader names all of them in one error. The sequence $​{} with no variable name stays literal text.

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

adapters:
  - id: pricing
    protocol: openapi
    upstream: "http://${PRICING_HOST:-127.0.0.1}:${PRICING_PORT:-9440}"
    auth:
      type: bearer
      header: Authorization

Validation rules

Validation runs after interpolation and deserialization. Every failure collects into one ConfigError::Validation, so one run reports all of them.

• Unknown keys. Every section applies deny_unknown_fields, so a typo such as recieipts fails at parse time, before validation.
• At least one adapter. An empty adapter list is rejected.
• Unique adapter ids. Duplicates are rejected by string comparison, and so are empty ids.
• Unique edge ids. The same rule, including empty ids.
• Reference integrity. Every edge.expose_from matches an adapter id declared in the same file.
• Auth completeness. type takes an enumerated value; bearer and api_key require a header.
• Signing key present. kernel.signing_key is a non-empty string.
• Logging values. level and format take values from their fixed sets.

Loading from Rust

Programs that embed the kernel load the file through the chio-config crate.

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 functions interpolate, parse with deny_unknown_fields, and validate before returning. Failures arrive as ConfigError with the variants Io, Interpolation, Parse, and Validation. A CI check for the runtime schema is a small Rust test that calls load_from_file and asserts Ok.

chio start runs the sidecar with zero-config defaults and takes no --config flag. Subcommands and embedded runtimes that read chio.yaml opt in through their own flags or programmatic APIs.

CLI checks

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

# Spawn an agent under a HushSpec policy.
$ chio run --policy ./policy.yaml -- python agent.py --issue 416

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

# Scaffold a new project with a sample chio.yaml and policy.
$ chio init pricing

chio doctor runs six ordered health probes. The sixth parses chio.yaml, checks the two top-level marker keys version and policy, and reports errors with line and column anchors. chio doctor --fix scaffolds a minimal file with exactly those keys: version: 1 and policy: ./policy.yaml. The marker schema is its own contract; the kernel, adapters, and edges schema above is validated by chio_config::load_from_file.