Operations

Operating ranges on a host: render a definition into a bundle, bring the range up, tear it down, and run the applier, reaper, and doctor.

Workflow

A range becomes a running range in two commands on a prepared host:

Terminal

inspect-ranges render range.yaml -o bundle/
inspect-ranges up bundle/

A range declaring guest content needs a matching build first: your own (Building Ranges), or a published one that the first inspect eval (or an explicit pull) fetches automatically (Distribution). Images need no preparation either way: bare image: names resolve digest-verified on first use (Images). inspect-ranges doctor checks the host first and prints fixes for whatever is missing.

Each stage consumes only the verified output of the one before it: render emits a digest-manifested bundle, and up refuses to act on anything whose digests do not verify.

Moving builds and images between machines (push, pull, mirror, publish) is Distribution; the deployment-shape recipes are Images. This page walks the lifecycle; complete option listings for every command are in the CLI reference.

`up`

inspect-ranges up <bundle> realizes a rendered bundle into a running, ready range: every manifest digest verifies first (tampered, incomplete, unlisted-file, or path-escaping bundles refuse; boot.json is shape-validated before any value reaches a command), image digests re-verify against the cache, then the hardened range container comes up on the bundle’s own compose project, guests boot per boot.json, and readiness waits on every guest (daemon answering over vsock, then cloud-init status --wait succeeding, probed over the control channel). The hardened non-root-QEMU range image is built automatically and is required; there is no bypass.

up --from-spec range.yaml composes render into a temporary bundle first. --uplink-network supplies the deployment uplink for ranges that request egress. A second up of an identical bundle refuses, naming the running project and the exact down command.

On failure, the error names the stage and guest, the affected guests’ serial console logs are pulled into the project state directory (~/.local/state/inspect-ranges/projects/<project>/, next to the JSONL stage log), and the project tears down unless --keep is passed.

`down`

inspect-ranges down <project> tears down by recorded ownership (compose labels and deterministic names), never by live process state: it works from any process, after any crash, and twice in a row. down --all sweeps every ir- project discovered from the ownership registry, container labels, and volume names, attempting all of them and aggregating any failures. The sweep cannot tell a crashed project from one mid-boot, so run it only when nothing on the host should be live. A failed removal keeps the ownership record so a retry can still find the project.

`applier`

inspect-ranges applier --socket <path> serves the host side of a separated topology (driver on one machine, range host on another) on a unix socket, relaying guest control traffic; see Range Host. It runs the doctor readiness subset at startup and refuses to serve an unhealthy host; drivers reach it via INSPECT_RANGES_HOST=uds:<path>.

`reaper`

inspect-ranges reaper reclaims expired host leases from on-disk state in one sweep (--interval <s> runs it as a daemon). It reclaims on expiry alone, never probing liveness; a failed teardown frees nothing and the next sweep retries. See Range Host for the lease contract.

`doctor`

inspect-ranges doctor checks the host (virtualization devices, docker versions, networking sysctls, image tooling) plus four surface groups:

Realizer: the hardened range image, the daemon artifact, and the Go toolchain (warnings, not failures: up builds the image on demand and daemon-bundle publishes the artifact once per fleet).
Provider and host: entry-point registration, goldens, CID and host lease registry health with an expired-leases hint naming the reaper, lease origins this machine can resolve, and the selected backend itself: the applier socket probe when INSPECT_RANGES_HOST points at one, or resolution plus the bundle’s own probe for a registered backend.
Evidence: knob validity, a writability probe of a configured sink, and a warning when evidence resolves to instance-local storage (see Evidence).
Build: builds/recipe cache writability, recorded manifests and cached recipe bundles still parse, and whether a build nameserver is derivable from this host’s resolv.conf (see Building Ranges).

--fix-script emits the shell commands for whatever failed.

Current Boundaries

up realizes cold-boot bundles only: checkpoint instantiation is planned later work. provisioning, services, and vulnerabilities realize through build: a range declaring them refuses every content-consuming verb (range-not-built) until a matching build manifest exists, and boots its captured realized images once one does. users, misconfigurations, and data realize through build like the content sections, as do roles, defense, Active Directory, telemetry-bearing postures, and scheduled_activity (installed as persistent units in the captured images), so nothing boots with silently missing content. Windows guests are supported (goldens derive locally with images derive-windows). Bundles are trusted operator input: verification proves integrity, not provenance (bundle signing is planned as part of image-distribution work).