Security model

Capsule is designed for private, owner-operated Firecracker hosts. The control API is sensitive infrastructure; Firecracker isolation does not make arbitrary untrusted code risk-free.

Control-plane accessCopy Anchor Link

• Bind the host API to localhost, a private interface, or a Tailnet address.
• Prefer signed cap1 tokens with a short expiry and narrowly scoped commands.
• Revoke a signed token by JTI when it is no longer needed.
• Keep the local JSONL audit log rotated and reviewed.
• Do not expose the host API to the public internet.

A legacy static bearer token is available only for private-lab bootstrap. Use signed, scoped tokens for normal automation.

Guest isolationCopy Anchor Link

Capsule uses Firecracker, jailer, cgroup v2 limits, per-VM networking, nftables policy, and vsock management. The guest cannot reach unrelated host services through the VM gateway. Guest SSH is not part of the normal control path.

Those are meaningful boundaries, not a warranty or a substitute for patching the host kernel and Firecracker.

Image intakeCopy Anchor Link

Treat every OCI image as untrusted input. Capsule verifies registry digests and applies OCI layers through a bounded traversal-safe extractor, but a digest identifies bytes; it does not establish trust.

For sensitive hosts:

• pin imports by digest;
• add signature, attestation, SBOM, and vulnerability policy before broad intake;
• keep imported root filesystems and snapshots permissioned appropriately; and
• avoid enabling private-registry access unless the registry is explicitly trusted.

Host-held secretsCopy Anchor Link

Capsule stores secret references, not secret values, in the host configuration. A guest requests a secret-bound HTTPS operation through an explicit mediator, which resolves the host-side source and constrains the destination to the configured HTTPS host and path.

This is not transparent credential proxying. Any workload inside a VM can use a secret bound to that VM, and the configured destination is trusted with that credential. Bind the narrowest practical hostname and path; never use echo or debug endpoints for secret-bearing requests.

Hardening checklistCopy Anchor Link

• Use a private API listener and signed scoped tokens.
• Enable the VM reaper and set TTLs.
• Restrict egress, especially for secret-bearing workloads.
• Patch the Linux host and Firecracker.
• Pin imported images and establish admission policy.
• Rotate and inspect audit logs.
• Test upgrades and restores on non-sensitive workloads first.

See operations for routine host checks and cleanup.