Node Preflight

What chio doctor answers

chio doctor is the preflight. It runs a fixed set of six probes in a fixed order, aggregates their reports, and derives one process exit code from the worst severity any of them observed. It is aimed at a developer workspace and at a CI job about to build against Chio: the first probe shells out to cargo and two of the six read files relative to the working directory. On a production host running a prebuilt binary it still runs, and the toolchain probe still fails it. Read the per-probe sections before wiring it into a runtime health check.

The command is shipped and its JSON envelope is versioned (chio.doctor.v1). Its diagnostics carry a weaker promise. Each urn:chio:error:cli:doctor-* entry in spec/errors/registry.yaml declares its own severity and stability, and the registry reads:

The severity column is the registry’s own declaration, and it agrees with the worst severity the corresponding probe can emit. Stability is the column a CI gate has to read: branch on the exit code and the probe names, which integration tests pin, and treat message text as text.

Read the scope narrowly. Each probe reads the local filesystem, the environment, an external HTTP endpoint, or the output of cargo --version. No probe opens a Chio database, reads a policy, or evaluates a guard, and the only write the whole command can make is the --fix scaffold in the sixth probe.

Probe, report, severity

The whole subsystem is one small trait. A probe has a stable lowercase name and one method that consumes a read-only config and returns exactly one report. Probes are required not to panic: anything that goes wrong comes back as a report carrying a registry code, never as an unwind out of the runner.

pub trait Probe {
    /// Stable probe identifier. Must be lowercase ASCII, no spaces.
    fn name(&self) -> &'static str;

    /// Execute the probe.
    fn run(&self, config: &ProbeConfig) -> ProbeReport;
}

ProbeConfig is three fields and every probe receives the same one. skip_network is set from --skip-network or the environment, fix_enabled from --fix, and workdir is a test-only override that the binary always leaves as None, so in production every path-resolving probe roots at the current working directory.

ProbeReport is what serializes into the envelope.

Severity is an ordered enum, and the runner takes a running maximum over it. The ordering matters more than it looks, because Info sorts above Ok: a run in which nothing is configured reports "worst": "info" rather than "ok", and still exits 0.

The distinction between info and warning is the one to internalize. info means the probe had nothing to check: no registry configured, no bundle on disk, no endpoint in the environment. It is not a pass. A green chio doctor on an unconfigured host tells you almost nothing.

That claim is easiest to read from a real run against an empty directory: one ok, five info, exit 0. The chio_yaml probe prints an absolute path, so the last report names the directory the command ran in.

$ chio doctor

chio doctor
  [ok] toolchain (urn:chio:error:cli:other): Rust toolchain 1.96.0 satisfies workspace MSRV.
    cargo_version: cargo 1.96.0 (30a34c682 2026-05-25)
  [info] oci (urn:chio:error:cli:other): No guard OCI registry configured. Skipping reachability probe.
    help: Set CHIO_GUARD_REGISTRY or add a `registry:` line to chio.yaml to enable the OCI reachability probe.
  [info] cosign (urn:chio:error:cli:other): No guard bundle configured. Skipping cosign freshness probe.
    help: Set CHIO_GUARD_BUNDLE or place a sigstore bundle at .chio/guard-bundle.sigstore.json to enable this probe.
  [info] otel (urn:chio:error:cli:other): No OTLP endpoint configured. Skipping OTEL probe.
    help: Set OTEL_EXPORTER_OTLP_ENDPOINT (or the receipt-specific CHIO_OTEL_RECEIPT_EXPORTER_ENDPOINT) to enable the probe.
  [info] kernel_runtime (urn:chio:error:cli:other): No kernel metrics URL configured. Skipping chio_kernel_dispatch_inflight gauge probe.
    help: Set CHIO_KERNEL_METRICS_URL to the chio-tower /metrics URL to enable this probe.
  [info] chio_yaml (urn:chio:error:cli:other): No chio.yaml found at ~/chio/chio.yaml.
    help: Run `chio doctor --fix` to scaffold a minimal chio.yaml, or create one by hand.

summary: worst severity = info, exit code = 0

Five of the six probes report that they had nothing to reach. The summary line still reads exit code 0, which is the point: this host has passed nothing except its toolchain check.

How a run proceeds

The order is built once, in code, and is not configurable from the command line:

/// Build the standard probe set in the canonical order: toolchain,
/// OCI, cosign, OTEL, kernel runtime, chio.yaml.
#[must_use]
pub fn standard(config: ProbeConfig) -> Self {
    Self::new(config)
        .with_probe(Box::new(ToolchainProbe::default()))
        .with_probe(Box::new(OciProbe::default()))
        .with_probe(Box::new(CosignProbe::default()))
        .with_probe(Box::new(OtelProbe::default()))
        .with_probe(Box::new(KernelRuntimeProbe::default()))
        .with_probe(Box::new(ChioYamlProbe::default()))
}

1. toolchain

Shells out to cargo --version, parses the semver out of the second whitespace-delimited field, and compares major and minor only. Then it line-scans the root Cargo.toml for a rust-version key and rust-toolchain.toml for a channel key. Older than the MSRV is an error; a pinned channel whose major and minor differ from the active cargo is an error. All four of its failure paths carry urn:chio:error:cli:doctor-toolchain-mismatch.

This probe is the only one that can fail an otherwise clean host, and it fails hard. Three conditions collapse to the same error: no cargo on PATH, a cargo --version that exits non-zero, and output the parser cannot read. The first two report Failed to invoke `cargo --version`. and exit 1. On a production host running a prebuilt chio binary with no Rust installed, that is the result of a bare chio doctor.

Run against the Chio workspace root, the two values it finds are rust-version = "1.94" in Cargo.toml and channel = "1.94.1" in rust-toolchain.toml, so any cargo outside 1.94 fails the pin comparison and any cargo below 1.94 fails the MSRV comparison.

The rest of the parsing is shallow, and the shallowness is load-bearing. channel = "stable" yields no numeric pair, so the pin comparison is skipped without a word. Both file reads root at the working directory, so running from a subdirectory finds neither file, and with no root manifest the report still reports the active toolchain as satisfying a workspace MSRV it never found. That is the run captured above: the only context key is cargo_version, because there was no manifest and no pin to compare against. The module header calls that case fail-closed; the code passes instead, and the code is the authority. Read the msrv and pinned_channel context keys to know whether a comparison happened, and do not assume cargo_version is always there: the unparseable-output branch attaches neither help nor context.

2. oci

Resolves a registry reference from two environment variables and then a registry: line in chio.yaml, in that order. An environment variable set to the empty string counts as unset and falls through, which is the opposite of how the skip-network variable is read. The file fallback is a line scan, not a parse: it takes the first line whose leading whitespace is trimmed and whose remainder starts with registry:, at any nesting depth, so a key nested three levels down inside an unrelated block resolves the registry. With nothing resolved it reports info and stops. Otherwise it issues one HEAD with a 5 second timeout, to the reference itself if it starts with the four characters http and to https://{registry}/v2/ otherwise, and accepts 2xx, 401, or 404 as reachable.

Read that acceptance set literally. The probe establishes that a host resolves, terminates TLS, and answers; not that the endpoint is an OCI registry, that credentials work, or that your bundle is present. It sends no credential, which is why 401 counts as success. It also appends /v2/ to whatever was resolved, so a reference carrying a repository path (ghcr.io/example/chio) produces a URL that is not the registry API root. Every failure here is a warning and never blocks.

Scope it accordingly. registry is not a key in the runtime chio.yaml schema, and the variable the real pull path reads is a different one, CHIO_GUARD_REGISTRY_PASSWORD in cli/types/runtime.rs. A passing oci probe says nothing about how a bundle will actually be pulled.

3. cosign

Resolves a bundle path from CHIO_GUARD_BUNDLE or, failing that, .chio/guard-bundle.sigstore.json under the working directory if it exists. Only the second candidate is existence-checked. A CHIO_GUARD_BUNDLE pointing at a file that is gone is not info, it is a warning: Cannot read guard bundle {path}: {err} under doctor-cosign-stale. Once a path resolves the probe calls std::fs::metadata, takes modified() with a created() fallback, converts elapsed time to whole days, and warns strictly above 90. Exactly 90 days passes.

4. otel

Reads CHIO_OTEL_RECEIPT_EXPORTER_ENDPOINT first, then OTEL_EXPORTER_OTLP_ENDPOINT, records which one won in a source context key, and validates the string as a URL, prefixing http:// onto anything that does not already carry an http:// or https:// scheme. Surrounding whitespace is rejected outright, which catches the pasted-with-trailing-space case that otherwise produces a silent export failure much later. It never sends a span and never opens a socket, so --skip-network does not change its behavior at all; the parameter is named _config in the signature.

The check is a parse and nothing more. Once the scheme is filled in, anything url::Url::parse accepts passes: no host reachability, no port sanity, no OTLP path convention. A typo that still parses is a pass here and a silent export failure in production. An empty value counts as unset and reports info.

Neither variable is read by any other crate under crates/, and the workspace has no opentelemetry-otlp dependency that would resolve the standard one inside an SDK. A node’s actual OTLP destination comes from the telemetry.endpoint field of the runtime chio.yaml schema.

5. kernel_runtime

With CHIO_KERNEL_METRICS_URL unset the probe reports info and names the variable in its help text. With it set it GETs the URL on a 5 second timeout and substring-matches the body for one gauge name. It never inspects the HTTP status: a 401, a 404, or a 500 whose body lacks the string all produce the same Metrics endpoint did not expose the chio_kernel_dispatch_inflight gauge. warning as a healthy endpoint that does not export it. Every failure mode here, including a connection failure and a body it cannot read, is a warning.

Two things follow. That route sits behind require_sidecar_control_middleware, the same admin gate as the approval routes, and this probe sends no credential. And the body it would get past that gate is composed in handle_metrics from the kernel guard metric families (chio_guard_verdict_total, chio_guard_deny_total, and the rest), the OTEL-drop, signing-queue-block, settlement-unresolved and ambiguous-dispatch families, the receipt watchdog gauges, the http-core mediation-edge families, and the alert pack. None of them is an inflight gauge. Pointed at a live endpoint, credentialed or not, this probe warns. Read Node Observability for what is actually exported.

All four of its failure branches carry urn:chio:error:cli:doctor-otel-unresolved, which the registry entry itself scopes to "the OTLP endpoint or kernel runtime metrics". The collision is deliberate, not a bug, but it means a code-based alert cannot tell probe 4 from probe 5. Split on the probe field.

6. chio_yaml

Reads ./chio.yaml, parses it with serde_yml, requires a top-level mapping, and requires two keys to be present: version and policy. Presence is the whole check. Values are never inspected, extra top-level keys are ignored, and nothing validates that policy names a file that exists. Calling it a schema probe oversells it; it is a two-key marker test that also proves the document parses.

A parse failure carries the parser’s line and column into line and column context keys so an editor can jump to the span, falling back to 0, 0 when serde_yml reports no location; missing keys report line: 1, column: 1 and list the names in missing. Only ErrorKind::NotFound is info. Any other read failure, including a directory at that path or a permission denial, is an error and exits 1.

The JSON envelope

--json, or the global --json / --format json, switches rendering to a single compact line on stdout. Four top-level fields, with exit_code carrying the same number the process will exit with, so a CI gate that already parsed the payload never needs to inspect the status separately.

let payload = serde_json::json!({
    "schema": "chio.doctor.v1",
    "worst": run.worst,
    "exit_code": run.exit_code(),
    "reports": run.reports,
});

A run from an empty directory with a registry resolved and the network skipped. serde_json::to_writer emits one compact line, so the capture pipes it through jq to read. Note the key order: it is alphabetical rather than the ProbeReport declaration order, because the workspace does not enable serde_json’s preserve_order feature and serde_json::Map is therefore a BTreeMap. Parse the payload; do not match it as text.

$ CHIO_GUARD_REGISTRY=ghcr.io/example/chio \
  chio doctor --json --skip-network | jq .

{
  "exit_code": 0,
  "reports": [
    {
      "code": "urn:chio:error:cli:other",
      "context": [
        {
          "key": "cargo_version",
          "value": "cargo 1.96.0 (30a34c682 2026-05-25)"
        }
      ],
      "help": null,
      "message": "Rust toolchain 1.96.0 satisfies workspace MSRV.",
      "probe": "toolchain",
      "repaired": false,
      "severity": "ok"
    },
    {
      "code": "urn:chio:error:cli:other",
      "context": [
        {
          "key": "registry",
          "value": "ghcr.io/example/chio"
        }
      ],
      "help": null,
      "message": "Registry endpoint ghcr.io/example/chio resolved. Network probe skipped.",
      "probe": "oci",
      "repaired": false,
      "severity": "ok"
    },
    {
      "code": "urn:chio:error:cli:other",
      "help": "Set CHIO_GUARD_BUNDLE or place a sigstore bundle at .chio/guard-bundle.sigstore.json to enable this probe.",
      "message": "No guard bundle configured. Skipping cosign freshness probe.",
      "probe": "cosign",
      "repaired": false,
      "severity": "info"
    },
    {
      "code": "urn:chio:error:cli:other",
      "help": "Set OTEL_EXPORTER_OTLP_ENDPOINT (or the receipt-specific CHIO_OTEL_RECEIPT_EXPORTER_ENDPOINT) to enable the probe.",
      "message": "No OTLP endpoint configured. Skipping OTEL probe.",
      "probe": "otel",
      "repaired": false,
      "severity": "info"
    },
    {
      "code": "urn:chio:error:cli:other",
      "help": "Set CHIO_KERNEL_METRICS_URL to the chio-tower /metrics URL to enable this probe.",
      "message": "No kernel metrics URL configured. Skipping chio_kernel_dispatch_inflight gauge probe.",
      "probe": "kernel_runtime",
      "repaired": false,
      "severity": "info"
    },
    {
      "code": "urn:chio:error:cli:other",
      "help": "Run `chio doctor --fix` to scaffold a minimal chio.yaml, or create one by hand.",
      "message": "No chio.yaml found at ~/chio/chio.yaml.",
      "probe": "chio_yaml",
      "repaired": false,
      "severity": "info"
    }
  ],
  "schema": "chio.doctor.v1",
  "worst": "info"
}

Note what is and is not there. context is omitted entirely on the four info reports because it is empty; help is present as null on the two ok reports, which have none. Every report carries urn:chio:error:cli:other, including the passing ones, which is why severity is the field to branch on. The human renderer prints the same data under a leading chio doctor line, one two-space-indented [ok] probe (code): message per report, then further-indented help: and context lines and a repaired: yes line where it applies, closing with summary: worst severity = ..., exit code = .... The warning marker is [warn], not [warning], which is the one place the human and JSON channels disagree on a spelling.

--fix repairs exactly one thing

The flag is documented as running idempotent repairs and rejecting destructive ones. No runtime check classifies a repair. The rule holds because exactly one probe reads fix_enabled at all, in exactly one branch: chio_yaml, on ErrorKind::NotFound, writes a two-line file.

version: 1
policy: ./policy.yaml

The write uses create_new(true), so it can only ever create. If the file appeared between the failed read and the create, the AlreadyExists arm re-reads and validates instead of clobbering. On success the report is ok with repaired: true, a created: true context key, and the help line Review the scaffolded policy path before running production workloads. The flag’s own clap help says repairs run "after probes complete"; they do not. The repair happens inline, inside the sixth probe, in place of the report it would otherwise have emitted.

What it does not do matters more. It will not repair a chio.yaml that exists and is missing keys, because that path never consults the flag. It will not create the ./policy.yaml the scaffold points at, and nothing ever checks that the target exists. It will not re-pull a stale bundle, install a toolchain, or write an environment variable. On a host where all six probes are already green it is a no-op.

The network skip, and why CI is safe

Two switches set the same bit: --skip-network and the environment variable CHIO_DOCTOR_SKIP_NETWORK. The environment check is presence-only (std::env::var(...).is_ok()), so exporting it empty counts as set; there is no =0 that turns it back off.

It is resolved twice on purpose. cmd_doctor folds both switches into ProbeConfig::skip_network before the runner is built, and the two probes that would reach out also re-check the variable themselves, so a library caller passing skip_network: false still gets the skip when the variable is exported.

Only oci and kernel_runtime build an HTTP client, both with a 5 second timeout, and both carry an explicit egress allowance comment marking them as diagnostic probes against a user-configured endpoint rather than substrate tool egress.

The CI recipe follows from the exit-code table. In a sandbox with no egress, run chio doctor --json --skip-network and gate on the status. All six probes still run; the two that would reach out resolve their target and report it without opening a socket, so no timeout can stall the job. Dropping the skip does not change the gate, because every network failure the doctor can produce is a warning worth 0. The skip buys the five seconds per probe, not a different verdict.

Guarantees and limits

Next Steps

• Health & Readiness · the same question asked of a process that is already running, and why liveness and readiness answer differently
• Node Lifecycle · what happens after preflight passes: startup ordering, and the refusals that stop a boot
• chio.yaml Configuration · the runtime schema the sixth probe does not validate
• Node Observability · what a node actually exports on /metrics, and the gate in front of it
• Guard Supply Chain · what the cosign probe only pretends to check, and the gate that actually checks it
• CLI Reference · chio doctor alongside the rest of the command set