Docs / Hotcell / Drivers

Drivers

Compare the Docker, Firecracker and Apple VZ drivers, and choose one per daemon or per sandbox.

A driver is the runtime that backs each sandbox. All three drivers implement the same interface, so the REST API, SDKs and CLI behave the same whichever you choose. One daemon can run all three side by side.

Comparison

container firecracker applevz
Backed by Docker container Firecracker microVM Apple Virtualization microVM
Host Linux and macOS Linux with KVM (/dev/kvm) macOS on Apple Silicon
Kernel Shared with the host Own guest kernel Own guest kernel
Pause Stop with volume: workspace survives, processes don't Memory snapshot: processes survive resume Memory snapshot: processes survive resume
Network by default Docker network; default-deny optional on Linux No network device; gateway over vsock only No network device; gateway over vsock only
Opt-in NAT network interface Not applicable networked: true Not supported in the current source
Warm pool HOTCELL_CONTAINER_WARM_POOL HOTCELL_FC_WARM_POOL HOTCELL_VZ_WARM_POOL
Default workspace disk Docker named volume 8 GiB (HOTCELL_FC_DISK_GB) 4 GiB (HOTCELL_VZ_DISK_GB)
Cold create, sequential median (benchmarks) 210 ms (Mac) 2,559 ms (GCP, nested virt) 2,618 ms (Mac)

Select a driver

Set the daemon default with HOTCELL_DRIVER (default container), in the environment or in ~/.hotcell/config.json. hotcell setup also writes it.

HOTCELL_DRIVER=firecracker hotcell start

Override it for one sandbox:

hotcell create --driver applevz

const vm = await client.getSandbox(undefined, { driver: "firecracker" });

curl -s -X POST http://127.0.0.1:4750/sandboxes \
  -H "Authorization: Bearer $(cat ~/.hotcell/api-key)" \
  -H "content-type: application/json" \
  -d '{"driver":"firecracker"}'

An unknown driver name returns 400. GET /info lists the available driver names in drivers and the daemon default in driver.

The Python SDK's get_sandbox doesn't take a driver argument in the current source; it uses the daemon default.

Container driver

The container driver backs each sandbox with a long-lived Docker container. A static Go guest agent (hotcell-agent) runs as PID 1 and serves exec, file, process and terminal operations. On Linux it uses a per-sandbox Unix socket; on Docker hosts that don't forward bind-mounted Unix sockets (such as Docker Desktop on macOS) it uses an authenticated loopback TCP port. Docker handles lifecycle, workspace volumes, resource limits and networking.

  • Works the same on macOS and Linux, because it uses the Docker Engine API.
  • /workspace is a named volume when persist is true (the default).
  • Memory, CPU and PID caps are enforced with cgroups. The minimum memory cap is 6 MiB (Docker's minimum).
  • HOTCELL_AGENT_BIN overrides the guest agent binary. The npm package ships the agent for the Docker host architecture; from source, build it with npm run build:agent.

The container driver shares the host kernel. Use a microVM driver when you need hardware isolation.

Firecracker driver

Each sandbox is a Firecracker microVM with its own kernel. The daemon converts the sandbox's OCI image to an ext4 rootfs and caches it in HOTCELL_FC_IMAGE_CACHE (default ~/.hotcell/fc/images).

  • Requirements: /dev/kvm, the firecracker binary (HOTCELL_FC_BIN, default firecracker on PATH), and a guest kernel and rootfs (HOTCELL_FC_KERNEL, HOTCELL_FC_ROOTFS). The kernel and rootfs defaults point into a source checkout.
  • No network device by default. The guest reaches the egress gateway over vsock through an in-guest loopback relay, so egress is denied by construction.
  • networked: true (REST and TypeScript SDK) gives the guest a NAT network interface for trusted workloads. Raw sockets then bypass the gateway's allowlist and logging. The driver drops all input from the guest's TAP device to the host, drops 169.254.0.0/16 (cloud metadata), disables IPv6 on the TAP and blocks routing into other sandboxes. Setting it up needs root or CAP_NET_ADMIN.
  • writableRootfs: true (REST) gives the guest a private writable rootfs without a network device, for workloads that write outside /workspace (for example apt or installs into /opt).
  • cpuset (REST) pins the Firecracker process to a taskset-style CPU list such as "0-7".

Apple VZ driver

Each sandbox is a microVM run by the signed hotcell-vz Swift helper through Apple's Virtualization framework.

  • Requirements: macOS on Apple Silicon. The helper and guest runtime are downloaded on demand for npm installs, or built with npm run build:vz from source.
  • No network device. Egress goes over vsock to the gateway only, which makes this the kernel-enforced default-deny option on a Mac. Default-deny on Docker Desktop is advisory only.
  • Converted rootfs images are cached in HOTCELL_VZ_IMAGE_CACHE (default ~/.hotcell/vz/images).

MicroVM boot concurrency

Cold microVM creates go through a boot scheduler. HOTCELL_MICROVM_BOOT_CONCURRENCY (default 4) limits simultaneous cold boots; 0 means unlimited. A queued create waits up to HOTCELL_MICROVM_BOOT_QUEUE_TIMEOUT_MS (default 120000). While it waits, the sandbox's statusReason is queued for microVM boot, and GET /capacity reports the queue under boot.