Architecture

Capsule turns a Linux machine with KVM into a private, single-host sandbox platform. It is deliberately not a managed cloud service or a multi-region fleet scheduler.

Capsule CLI / Setup Center / Mission Control
  -> private HTTP control API
  -> host orchestrator
  -> Firecracker jailer + microVM
  -> vsock
  -> Capsule guest agent

The same executable serves as the client, host service, lifecycle controller, UI, and guest agent. The normal management path is vsock; a guest SSH service is not required.

Control planeCopy Anchor Link

A Capsule host exposes a typed, versioned private API for health checks, VM lifecycle, bounded guest execution, image inventory/import, resources, and events. The embedded OpenAPI contract is the canonical API surface and generated SDKs track its contract hash.

Keep the API on a private network. Capsule is designed for an owner-operated host, not a public sandbox endpoint.

VM boundaryCopy Anchor Link

Every Capsule gets its own:

• cloned root filesystem;
• Firecracker jailer chroot and per-VM UID/GID;
• cgroup v2 CPU and memory limits;
• tap interface and per-VM nftables chains;
• vsock management device; and
• named egress policy.

The available egress modes are none, internet, restricted, and allowlist. Allowlist mode uses a VM-local DNS path and expiring nftables destinations; it is an IPv4, destination-IP control, not proof of the TLS hostname used by every subsequent connection.

Images and dataCopy Anchor Link

Capsule boots immutable block root filesystems rather than running a container daemon. OCI imports resolve and verify registry content, apply layers through a bounded traversal-safe process, inject the guest agent, build an ext4 root filesystem, and publish a content-addressed image.

File movement follows this path:

client -> private API -> host temporary file -> vsock -> guest file

Transfers are checksum-verified. Snapshot restore validates compatibility metadata such as Firecracker version, architecture, CPU model, kernel, and root filesystem hashes before proceeding.

What Capsule does not claimCopy Anchor Link

Capsule does not yet provide multi-host scheduling, fleet high availability, external identity integration, IPv6 egress policy, or broad compatibility coverage across kernels and OCI userlands. It is research software for a host you operate and understand.