@capsuleos/firecracker

Preview Firecracker microVM provider for CapsuleOS. The package is an unprivileged adapter: an injected, application-owned MicrovmSupervisor owns KVM, Firecracker, the jailer, cgroups, network namespaces, TAP devices, disks, sockets, and restart reconciliation.

import { firecracker } from "@capsuleos/firecracker";
import { createUnixMicrovmSupervisorClient } from "@capsuleos/microvm-supervisor";

const supervisor = createUnixMicrovmSupervisorClient({
  socketPath: "/run/capsuleos/hostd.sock",
});

const provider = firecracker({
  supervisor,
  namespace: "preview-agents",
  image: {
    template: "capsuleos-agent",
    reference: "capsuleos-agent",
    version: "2026.08.02",
    manifestDigest: "sha256:...",
    architecture: "x86_64",
  },
  guestTokenProvider: (sandboxId) => createTokenProviderFor(sandboxId),
});

The provider accepts only that exact supervisor template identity. stop() pauses the exact VMM and start() resumes it; neither operation cold-boots or allocates a replacement. Guest process and file operations use authenticated Capsule guest protocol v1 through the supervisor's private virtio-vsock stream. The provider never closes the injected supervisor.

V1 intentionally does not expose Firecracker snapshots or ingress. It rejects GPU and disk requests, restricted egress, privileged execution, host environment inheritance, host networking, host paths, and host devices.

The provider advertises process.stdin, so @capsuleos/ai-sdk-harness automatically uses its loopback process tunnel. Firecracker therefore needs no public or arbitrary ingress for Claude Code or Codex Harness sessions.

The package does not turn an arbitrary Linux machine into a production jailer host. This repository does not yet ship an installable capsule-hostd or production Firecracker process controller, so the adapter remains preview-only until an exact Firecracker/jailer, kernel, rootfs, and host configuration passes the protected native acceptance and leak gates.