Operations

Capsule is an experimental single-host control plane. Operate it like infrastructure: inspect before changing, use a TTL for every disposable workload, and verify state after a restore or cleanup.

Health and inventoryCopy Anchor Link

capsule doctor
capsule doctor --json
capsule ps
capsule images
capsule resources --json
capsule events scout --lines 20

doctor checks host and VM artifact consistency. images lists immutable kernel and root filesystem metadata; new VM records preserve the selected image ID and the relevant content hashes.

CleanupCopy Anchor Link

Destroy individual workspaces explicitly:

capsule pop scout

For stale stopped-VM artifacts or Capsule-owned tap and nftables objects, use the conservative repair path:

capsule repair

Repair is deliberately limited to Capsule-prefixed artifacts. It is not a generic host-network cleanup tool.

Snapshots and clonesCopy Anchor Link

A snapshot records a manifest alongside its memory, state, and root filesystem artifacts. Restore validates size, hashes, architecture, CPU model, Firecracker version, kernel, base root filesystem, and CPU template metadata.

Cloning defaults to a fresh VM identity: new tap device, guest IP, MAC address, vsock CID, hostname, and machine ID. Memory-snapshot cloning is experimental because an in-memory Firecracker snapshot can retain device identity.

Logs and telemetryCopy Anchor Link

The local JSONL audit log remains the authoritative record of API activity. OpenTelemetry support is operational telemetry, not an audit replacement. Collecting metrics does not remove the need to review failed API operations, VM pressure, storage headroom, and reaper behavior.

Before an upgradeCopy Anchor Link

1. Export or snapshot the state you need to retain.
2. Run capsule doctor and clear known inconsistencies.
3. Test the new build on a disposable host and workload.
4. Verify a fresh VM, a bounded guest command, egress policy, file transfer, and cleanup.
5. Only then touch persistent or sensitive workloads.