Getting started

Capsule is an experimental, owner-operated Firecracker control plane. Start on a disposable Linux machine and treat every API credential, imported image, and agent workload as security-sensitive.

Before you installCopy Anchor Link

A host needs Linux, KVM virtualization, Firecracker, and private networking. Setup Center checks the host prerequisites before it makes changes and rejects public or wildcard API listen addresses.

Use a private LAN address, loopback, or a Tailnet interface for the control plane. Do not expose a Capsule host directly to the public internet.

Public Linux host release statusCopy Anchor Link

A public Linux host artifact is not yet published. Do not rely on stale releases/latest download URLs or use Capsule as production infrastructure.

The host setup flow is currently for invited preview builds and authorized source users. Setup Center chooses whether the machine becomes a host or connects to an existing private host, then checks KVM, Firecracker, networking, host isolation, and the service manager before it changes the machine.

Launch one CapsuleCopy Anchor Link

Once you have an authorized preview build and completed setup, create a short-lived VM, run a bounded command, and explicitly tear it down:

capsule new --name scout --image agent-full --cpu 2 --memory 2048 --ttl 2h --egress restricted
capsule raw exec --cwd /workspace --timeout 60s scout -- 'hostname; python3 -c "print(2+2)"'
capsule pop scout

pop destroys the microVM. A TTL is a safety net, not a reason to skip cleanup.

Connect a macOS clientCopy Anchor Link

macOS is a Capsule client, not a Firecracker host. Download the matching client build, then use Setup Center to verify and save the URL and scoped token for a private Linux host:

curl -fL https://capsules.lol/downloads/capsule-darwin-arm64 -o capsule-darwin-arm64
chmod +x capsule-darwin-arm64
./capsule-darwin-arm64 install

Use capsule-darwin-amd64 on Intel Macs. Preview binaries are checksum-published but are not yet Developer ID signed or notarized.

First safety checksCopy Anchor Link

Before placing a real workload in Capsule:

1. Run capsule doctor and read every warning.
2. Create short-lived scoped tokens instead of handing automation a broad bootstrap token.
3. Use --egress restricted or an explicit allowlist for workloads that do not need open internet access.
4. Keep the host, Firecracker, and imported images patched.

Read the security model before importing third-party OCI images or binding a host-held secret.