Sandbox Lifecycle

A sandbox is one Firecracker microVM. The sandbox.Manager interface has exactly three methods, and the HTTP API maps one endpoint to each:

type Manager interface {
	Create(ctx context.Context, languagePack string) (*Sandbox, error)
	Exec(ctx context.Context, id string, req proto.ExecRequest) (proto.ExecResult, error)
	Delete(ctx context.Context, id string) error
}

The Firecracker-backed implementation lives in pkg/sandbox/firecracker.

Create: boot a microVM

POST /sandboxes → Manager.Create:

1. Resolve the language pack. Look up languagePack in the registry. An unknown name returns ErrUnknownPack → HTTP 400. This happens before any VM work, so it's cheap.

2. Allocate identity and workspace. Generate sb_<hex>, create ${TMPDIR}/emberd/<id>/, open vm.log.

3. Set up the control channel. Allocate a guest context ID (CID, counting up from 3) and pick the host vsock socket path <dir>/vsock.sock.

4. Build the Firecracker config:

   • kernel = vmlinux-6.1.155, initrd = emberd-initramfs.cpio
   • rootfs drive = the pack's squashfs, read-only, root device (/dev/vda)
   • a hybrid-vsock device pointing at vsock.sock + the guest CID
   • 1 vCPU, 256 MiB (configurable)
   • kernel args = base args plus emberd.interpreter=<pack interpreter>

5. Launch the VMM. Build the firecracker command (custom binary path, per-VM API socket, console wired to a log file) and Start it under a background context that lives for the VM's whole lifetime, not the HTTP request context, which would cancel the VM when the request returns.

6. Record the handle in the manager's map and return { "id": "sb_..." } with HTTP 201.

7. Wait for readiness. Before returning, Create blocks on waitReady, which polls the guest vsock control plane (50ms interval, BootTimeout default 15s). A successful hybrid-vsock CONNECT/OK handshake only happens once emberd-init is past bootstrap and listening, so it's a precise readiness signal, not a fixed sleep. If the guest never comes up, the half-booted VM is torn down and an error returned.

Exec: run code in the guest

POST /sandboxes/{id}/exec → Manager.Exec:

1. Look up the live VM by ID (unknown → ErrNotFound → 404).
2. proto.DialGuest(vsockUDS, GuestPort): connect to the host vsock socket and perform the Firecracker hybrid-vsock CONNECT/OK handshake.
3. Set a deadline on the connection: timeout_ms + 10s, or 60s if no timeout was given, so a wedged guest can't hang the request.
4. WriteMessage(conn, ExecRequest) then ReadMessage(conn, &ExecResult).
5. Map the result to the HTTP response.

Inside the guest, emberd-init writes the code to a temp file, runs it under the pack's interpreter with the request's stdin piped in, and captures stdout/stderr/exit. A non-zero exit from your program is a normal result (exit_code set, error empty); only a failure to launch the interpreter populates error. See the control plane for the wire details and the guest rootfs for how the interpreter runs.

Delete: tear it down

DELETE /sandboxes/{id} → Manager.Delete:

1. Remove the handle from the map (unknown → ErrNotFound → 404).
2. StopVMM() sends SIGTERM to the firecracker process for a clean VMM shutdown.
3. Wait with a 5-second bound; cancel the VM's context (which kills the process if the graceful stop stalled).
4. RemoveAll the work directory.

The per-VM tmpfs overlay dies with the VM, so there's nothing to garbage-collect inside the guest; the writable layer simply ceases to exist.

State machine

There is no "paused" or "stopped-but-kept" state in v0.1: a sandbox is either running or gone. Snapshotting changes that in v0.2.