Firecracker
@magistr/firecrackerv2026.06.12.2
01README
Firecracker microVM lifecycle management via SSH + the Unix-socket REST API. One model instance = one microVM socket.
Model @magistr/firecracker:
- Configure machine, boot source, drives, network interfaces, vsock, entropy.
- start / stop / pause / resume; send_ctrl_alt_del.
- snapshot / restore; wait_serial (poll serial log for snapshot baking).
- kill_vmm (precision kill via PID sidecar); start_vmm (idempotent warm-start).
- Host bootstrap: install_firecracker, install_guest_kernel (modern CI vmlinux), setup_tap, build_ubuntu_rootfs (debootstrap Ubuntu + glibc Claude Code, init=/opt/fc-agent.sh), update_agent_script (deploy PID-1 agent).
Workflows:
@magistr/fc-install-firecracker— install/upgrade the Firecracker binary.@magistr/fc-bake-snapshot— boot, wait for agent poll-state, snapshot, tear down — leaves a warm agent snapshot for fast restore.@magistr/fc-run-agent— run a Claude Code agent task inside a microVM, with guaranteed cleanup.
02Release Notes
Merge pull request #11 from umag/chore/firecracker-utf8-release
release(firecracker): 2026.06.12.2 — UTF-8-safe fabric base64
03Models
@magistr/firecrackerv2026.06.12.2extensions/models/firecracker.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| host | string | SSH host/IP of the machine running Firecracker — host key verification is disabled; use on trusted networks only |
| user | string | SSH username (default: root) |
| socketPath | string | Path to the Firecracker Unix socket on the remote host (e.g. /run/firecracker.socket). One model instance = one microVM socket. |
| netns? | union | Optional Linux network namespace for this microVM. When set, start_vmm launches Firecracker inside it (ip netns exec) and kill_vmm tears it down — lets many clones of one base snapshot run without IP/gateway overlap. Pair with setup_tap's netns mode. Omit for the single-VM root-namespace path (unchanged). |
fn status()
Get instance info and VM state
fn configure(vcpuCount: number, memSizeMib: number, smt?: boolean, trackDirtyPages?: boolean)
Set machine vCPUs and memory. PRE-BOOT ONLY — must be called before start. Returns HTTP 400 (fault_message) if VM is already running.
| Argument | Type | Description |
|---|---|---|
| vcpuCount | number | vCPU count (1–32) |
| memSizeMib | number | Memory in MiB (minimum 128) |
| smt? | boolean | Enable simultaneous multi-threading |
| trackDirtyPages? | boolean | Enable dirty-page tracking (needed for live migration) |
fn set_boot(kernelImagePath: string, bootArgs: string, initrdPath?: string)
Set boot source (kernel image path, boot args, optional initrd). PRE-BOOT ONLY.
| Argument | Type | Description |
|---|---|---|
| kernelImagePath | string | Path to the uncompressed kernel image on the Firecracker host |
| bootArgs | string | Kernel boot arguments (e.g. 'console=ttyS0 reboot=k panic=1 pci=off') |
| initrdPath? | string | Optional path to initrd on the Firecracker host |
fn set_drive(driveId: string, pathOnHost: string, isRootDevice: boolean, isReadOnly: boolean)
Set a drive (rootfs or data). Idempotent PUT — creates or updates by drive_id. PRE-BOOT ONLY for root drives.
| Argument | Type | Description |
|---|---|---|
| driveId | string | Drive identifier (e.g. 'rootfs', 'data1') |
| pathOnHost | string | Path to the drive image file on the Firecracker host |
| isRootDevice | boolean | Whether this is the root block device |
| isReadOnly | boolean | Mount as read-only |
fn set_network(ifaceId: string, hostDevName: string, guestMac?: string)
Set a network interface. Idempotent PUT. PRE-BOOT ONLY. The tap device must pre-exist on the host.
| Argument | Type | Description |
|---|---|---|
| ifaceId | string | Interface identifier (e.g. 'eth0') |
| hostDevName | string | Host tap device name (e.g. 'tap0', max 15 chars) |
| guestMac? | string | Guest MAC address — auto-assigned by Firecracker if omitted |
fn set_vsock(guestCid: number, udsPath: string)
Configure a virtio-vsock device. PRE-BOOT ONLY — call before start. On snapshot restore, pass vsock_override to change the UDS path per-VM.
| Argument | Type | Description |
|---|---|---|
| guestCid | number | Guest CID (context identifier) for the vsock device — must be ≥ 3 |
| udsPath | string | Host-side Unix socket path for the vsock device (e.g. /tmp/fc-agent-1.vsock) |
fn build_ubuntu_rootfs(claudeCodeVersion: string, rootfsPath: string, sizeMib: number, suite: string, force: boolean)
Build a fresh Ubuntu rootfs (ext4) from scratch via debootstrap, layered with the glibc claude-linux-x64 binary + ca-certificates, curl, git, python3, iproute2, and the PID-1 agent script (booted via init=/opt/fc-agent.sh). Replaces the old Alpine/musl rootfs to avoid missing-CA-cert / BusyBox quirks. Runs the heavy build in the BACKGROUND on the host and returns immediately — poll completion with wait_serial(target='ROOTFS BUILD COMPLETE', logPath='/var/log/fc-rootfs-build.log', timeoutSeconds=
| Argument | Type | Description |
|---|---|---|
| claudeCodeVersion | string | claude-code release tag (default: latest). Uses the glibc claude-linux-x64 build. |
| rootfsPath | string | Final path for the rootfs image on the Firecracker host |
| sizeMib | number | Size of the rootfs image in MiB |
| suite | string | Ubuntu suite/codename for debootstrap (e.g. noble, jammy) |
| force | boolean | Rebuild even if the ready-marker already exists |
fn update_agent_script(rootfsPath: string, mountPoint: string)
Replace /opt/fc-agent.sh in the rootfs image with the current PID-1 Ubuntu agent (init=/opt/fc-agent.sh). The VM must NOT be running — unmount happens after write. Use this to deploy a new agent version without a full rootfs rebuild.
| Argument | Type | Description |
|---|---|---|
| rootfsPath | string | Path to the rootfs image on the Firecracker host |
| mountPoint | string | Temporary mount point (created if absent) |
fn wait_serial(target: string, logPath?: string, timeoutSeconds: number)
Poll the Firecracker process log file until a target string appears (serial console output). Use during snapshot baking to detect when guest reaches 'polling for task' state before pausing.
| Argument | Type | Description |
|---|---|---|
| target | string | String to wait for in the serial log (e.g. 'polling for task') |
| logPath? | string | Path to the FC log file on the host. Defaults to /var/log/<socket-basename>.log |
| timeoutSeconds | number | Max seconds to wait for the target string |
fn snapshot(snapshotPath: string, memFilePath: string, snapshotType: enum)
Snapshot the microVM state to disk. VM must be paused first (call pause()). Creates a memory + disk snapshot for fast restore.
| Argument | Type | Description |
|---|---|---|
| snapshotPath | string | Host path to write the snapshot file (e.g. /opt/firecracker/agent-snapshot.snap) |
| memFilePath | string | Host path to write the memory file (e.g. /opt/firecracker/agent-snapshot.mem) |
| snapshotType | enum | Full captures the entire state; Diff captures only changes since last snapshot |
fn restore(snapshotPath: string, memFilePath: string, vsockUdsPath?: string, ifaceId?: string, hostDevName?: string)
Restore a microVM from a snapshot. Requires a fresh Firecracker process (socket exists but no VM started). Use vsockUdsPath to give this instance its own vsock UDS path (avoids collisions between concurrent VMs).
| Argument | Type | Description |
|---|---|---|
| snapshotPath | string | Path to the snapshot file |
| memFilePath | string | Path to the memory file |
| vsockUdsPath? | string | Override vsock UDS path for this instance (vsock_override) — required when running concurrent VMs from the same snapshot |
| ifaceId? | string | Network interface id baked into the snapshot (e.g. 'eth0') to remap on restore. Pair with hostDevName to emit network_overrides — lets a clone bind its own per-VM tap. |
| hostDevName? | string | Host tap device to bind the baked interface to on restore (network_overrides). Requires ifaceId. |
fn start()
Start the microVM (InstanceStart). Call after all pre-boot configuration is complete.
fn stop()
Stop the microVM (InstanceHalt). Checks VM state first — idempotent if already stopped.
fn send_ctrl_alt_del()
Send Ctrl+Alt+Del to the guest for graceful shutdown. Requires guest ACPI support — silently ignored if the guest does not handle it.
fn pause()
Pause the microVM. VM must be in Running state.
fn resume()
Resume a paused microVM.
fn kill_vmm(vsockUdsPath?: string)
Kill the Firecracker process owning this socket (via PID sidecar, falls back to fuser). Removes socket, PID file, and vsock UDS files. Safe when no VM is running.
| Argument | Type | Description |
|---|---|---|
| vsockUdsPath? | string | vsock UDS base path — also removes {vsockUdsPath}_* side-car files |
fn set_entropy_device()
Configure a virtio-rng entropy device via PUT /entropy. PRE-BOOT ONLY — must be called before start. The guest gets entropy from the host's /dev/urandom, unblocking getrandom() and /dev/random inside the VM. Essential for TLS/crypto in musl-based guests.
fn install_firecracker(version?: string, arch?: string, installPath: string)
Download and install the latest Firecracker release binary from GitHub onto the host. Replaces /usr/local/bin/firecracker in-place. Idempotent: skips download if already at the target version.
| Argument | Type | Description |
|---|---|---|
| version? | string | Specific version tag to install (e.g. 'v1.12.0'). Defaults to latest GitHub release. |
| arch? | string | CPU architecture (e.g. 'x86_64', 'aarch64'). Auto-detected if omitted. |
| installPath | string | Destination path for the binary |
fn install_guest_kernel(kernelVersion: string, ciVersion: string, arch?: string, installPath: string, url?: string, force: boolean)
Download a modern Firecracker-tested guest kernel (vmlinux) from the Firecracker CI artifacts bucket and install it at installPath (default /opt/firecracker/vmlinux), backing up the previous kernel once to <installPath>.orig.bak. Replaces the legacy 4.14 kernel whose old crng/getrandom behavior blocked TLS/crypto. A snapshot must be re-baked after changing the kernel. Idempotent: records the installed version in /opt/firecracker/.guest-kernel-version and skips if it already matches unless force=
| Argument | Type | Description |
|---|---|---|
| kernelVersion | string | Kernel version available in the Firecracker CI bucket (e.g. 6.1.128, 5.10.233) |
| ciVersion | string | Firecracker CI artifacts prefix (e.g. v1.12) |
| arch? | string | CPU architecture (default: uname -m, e.g. x86_64) |
| installPath | string | Destination path for the kernel image |
| url? | string | Full override URL for the vmlinux image (bypasses ciVersion/kernelVersion) |
| force | boolean | Re-download even if the recorded version already matches |
fn setup_tap(tapName: string, hostIp: string, prefix: number, guestSubnet: string, netns?: union, vethSubnet: string)
Idempotent: create a TAP device on the host, assign an IP, and enable NAT masquerade so guest VMs can reach the internet. Safe to call on every workflow run — skips steps that are already done.
| Argument | Type | Description |
|---|---|---|
| tapName | string | TAP device name (default: tap0) |
| hostIp | string | Host IP on the TAP subnet (guest default gateway) |
| prefix | number | Subnet prefix length (default: 24 → /24) |
| guestSubnet | string | Guest subnet for NAT masquerade rule |
| netns? | union | Optional network namespace. When set, the tap + veth + NAT are built INSIDE this namespace so many clones of one base snapshot run without overlap (reusing the same guest IP). Omit for the single-VM root-namespace path (unchanged). |
| vethSubnet | string | Host↔namespace veth subnet (netns mode only). MUST be unique per concurrent VM; .1 is the host side, .2 the namespace side. Derive per-VM (e.g. 10.0.<index>.0/30). |
fn start_vmm(logPath?: string, vsockUdsPath?: string)
Start a Firecracker process and wait for the API socket. Idempotent: if the PID sidecar shows a live process with a ready socket, returns without starting a new one. When starting fresh, cleans up stale vsock UDS files to prevent Firecracker 'address in use' errors on snapshot restore.
| Argument | Type | Description |
|---|---|---|
| logPath? | string | Path to write Firecracker stderr/stdout on the host (default: /var/log/fc-<socket-basename>.log) |
| vsockUdsPath? | string | vsock UDS base path — stale files at this path and {path}_* are removed when starting fresh to avoid EADDRINUSE on snapshot restore |
fn fabric_up(concurrency: number, snapshotPath: string, memFilePath: string, queueRoot: string, netnsPrefix: string, tapName: string, tapIp: string, guestSubnet: string, port: number, oauthToken: string)
Factory: spawn a warm worker-VM pool. Fans out `concurrency` netns microVMs (each restored from the snapshot and running the looping agent) that pull tasks from a shared host queue served by a per-VM fabric daemon. One call brings up the whole pool concurrently; submit/poll/fabric_down drive it afterwards.
| Argument | Type | Description |
|---|---|---|
| concurrency | number | Pool size = max concurrent worker VMs (configurable; ~512MiB RAM each) |
| snapshotPath | string | |
| memFilePath | string | |
| queueRoot | string | |
| netnsPrefix | string | |
| tapName | string | |
| tapIp | string | |
| guestSubnet | string | |
| port | number | |
| oauthToken | string | Claude Code OAuth token; the daemon injects it at serve time (never written to the queue) |
fn submit(queueRoot: string, tasks: array)
Enqueue agent tasks onto the fabric queue (NON-BLOCKING, callable any time — including while tasks are running). Returns the generated task ids. Workers pull and run them as slots free up; the daemon injects the OAuth token at serve time so it is never written to the queue.
| Argument | Type | Description |
|---|---|---|
| queueRoot | string | |
| tasks | array |
fn poll(queueRoot: string, ids?: array)
Collect completed task results from the fabric (NON-BLOCKING, idempotent). Returns a map of task id -> result for every result posted so far (optionally filtered to `ids`), plus the number still pending in the queue.
| Argument | Type | Description |
|---|---|---|
| queueRoot | string | |
| ids? | array | If given, only report these ids |
fn fabric_down(concurrency: number, netnsPrefix: string, queueRoot: string)
Tear down the whole fabric: reap every worker VM (PID + socket + netns + NAT, exactly as kill_vmm), stop the daemons, and remove the queue root. Discovers the live workers by enumerating the host (netns list + socket/pid files for the prefix) so it reaps the ACTUAL pool regardless of the size it was brought up with — no worker leaks on a concurrency mismatch. `concurrency` is only a lower-bound fallback. Idempotent.
| Argument | Type | Description |
|---|---|---|
| concurrency | number | Lower-bound fallback only; the real pool is discovered from host state |
| netnsPrefix | string | |
| queueRoot | string |
fn fabric_recycle(concurrency: number, timeoutSeconds: number, queueRoot: string, netnsPrefix: string, tapName: string, tapIp: string, guestSubnet: string, port: number, snapshotPath: string, memFilePath: string, oauthToken: string)
Liveness watchdog: re-queue tasks claimed longer than `timeoutSeconds` ago (a wedged/hung worker) and restart the workers that were stuck on them, so a hung agent never permanently loses a pool slot. Idempotent; call periodically while a fabric is up.
| Argument | Type | Description |
|---|---|---|
| concurrency | number | |
| timeoutSeconds | number | |
| queueRoot | string | |
| netnsPrefix | string | |
| tapName | string | |
| tapIp | string | |
| guestSubnet | string | |
| port | number | |
| snapshotPath | string | |
| memFilePath | string | |
| oauthToken | string |
Resources
status(1h)— Instance info and current VM state
machineConfig(1h)— Machine configuration (vCPUs, memory)
action(1h)— Result of a lifecycle action
fabric(infinite)— Fabric pool state (queueRoot, concurrency, workers).
submitted(24h)— Ids of tasks enqueued onto the fabric in a submit call.
results(24h)— Completed fabric task results (id -> output) + pending count.
04Workflows
@magistr/fc-install-firecracker
Download and install the latest Firecracker binary on the remote host. Run once to upgrade from an old version that lacks /entropy-device support.
install
1.install-firecracker— Install latest Firecracker release binary
@magistr/fc-bake-snapshot
Update the agent script in the rootfs, boot a fresh Firecracker VM, wait for the agent to reach the polling-for-task state, snapshot, then tear down. Leaves /opt/firecracker/agent-snapshot.{snap,mem} ready for fc-run-agent. Uses only @magistr/firecracker methods — no @adam/cfgmgmt dependency.
cleanupKill any running Firecracker processes before bake
1.kill-bake-vmm— Kill any stale bake Firecracker process
2.kill-prod-vmm— Kill any running production Firecracker process
bakeUpdate agent script, boot VM, wait for agent to reach polling state, then snapshot. Cleanup and pre-warm at the end.
1.setup-tap— Idempotent TAP device + NAT setup
2.update-agent-script— Deploy the TAP+wget agent to the rootfs (VM must be stopped)
3.start-bake-vmm— Start fresh Firecracker process on bake socket
4.configure
5.set-entropy-device— Configure virtio-rng so guest TLS/crypto does not block on /dev/random
6.set-boot
7.set-drive
8.set-network
9.start-vm
10.wait-agent— Wait for agent to print "polling for task" on serial console
11.pause-vm
12.snapshot-vm
13.kill-bake-vmm— Clean up the bake VM process
14.pre-warm-prod— Start a fresh production Firecracker process (warm for next run)
@magistr/fc-run-agent
Run a Claude Code agent task inside a Firecracker microVM. Guest reaches the internet via TAP networking + host NAT. A simple TCP HTTP server on the host TAP IP serves the task JSON (with OAuth token) to the guest and collects the result. Two-job structure ensures cleanup always runs: Job 1 (run-agent): setup-tap → ensure-vmm-ready → deploy-server → restore-snapshot → inject-task → collect-result Job 2 (cleanup): depends on run-agent with type:always → stop-server → kill-vmm → pre-warm-nex
run-agentMain job: setup TAP → start warm VMM → server up → restore snapshot → inject task → collect result. Cleanup job (below) always runs after this regardless of success/failure.
1.setup-tap— Idempotent TAP device setup: creates tap0, assigns host IP, enables NAT masquerade so the guest can reach api.anthropic.com directly.
2.ensure-vmm-ready— Idempotent VMM start: reuses warm process if PID sidecar shows it alive, otherwise starts fresh.
3.deploy-server— Start TCP task/result server on tapIp:tapPort BEFORE restore-snapshot so it is ready when the VM resumes and begins polling GET /task.
4.restore-snapshot— Restore snapshot AFTER server deployed — VM resumes and immediately finds the TCP task server ready on tapIp:tapPort.
5.inject-task— Write task JSON to file; server delivers it on next guest GET /task
6.collect-result— Poll for result file written by guest POST /result
cleanupAlways-run cleanup: stop TCP server (PID kill), kill VMM (PID kill), pre-warm a fresh Firecracker for next run. Runs regardless of run-agent outcome.
1.stop-server— Kill TCP server via PID sidecar
2.kill-vmm— Kill Firecracker process via PID sidecar, clean socket files
3.pre-warm-next— Start a fresh Firecracker process so next run finds a warm VMM. Idempotent — no-op if already warm.
05Previous Versions
2026.06.12.1Jun 11, 2026
release: firecracker + fc-task-server 2026.06.12.1 — bundle CHANGELOG
Bump both to 2026.06.12.1 and add CHANGELOG.md to additionalFiles so the published archive carries the changelog + the updated README (task-fabric methods in the Methods list). No model behaviour change. CI publishes to stable.
Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com
2026.06.11.7Jun 11, 2026
Merge pull request #9 from umag/feat/fc-task-factory
firecracker: fast task fabric — warm worker pool + queue (factory) on top of netns
Modified 1 models
2026.06.09.20Jun 9, 2026
fc-task-server + firecracker: default Claude Code agent effort to low
Adds a configurable reasoning-effort control to the Firecracker microVM agent flow, defaulting to "low" so sandboxed agent runs stay fast and cheap.
@magistr/fc-task-server 2026.06.09.3
- inject_task gains an
effortarg: z.enum([low,medium,high,xhigh,max]) defaulting to "low", written into the task JSON served to the guest. - 3 new unit tests (default low, accepts a level, rejects unknown).
@magistr/firecracker 2026.06.09.20
- Guest agent script reads
effortfrom the task JSON and passes ${EFFORT:+--effort "$EFFORT"} toclaude --print(double-quoted; the value is enum-validated upstream). Pick up the new script via update_agent_script (or re-bake the rootfs).
Effort levels match the Claude Code CLI --effort flag
(low/medium/high/xhigh/max; max is Opus-tier only).
Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com
2026.06.09.19Jun 9, 2026
Add @magistr/firecracker and @magistr/fc-task-server extensions
Relocate both Firecracker microVM extensions into the workspace monorepo at Grade A (14/14), repackaged from the published registry versions.
@magistr/firecracker 2026.06.09.19
- Firecracker microVM lifecycle over SSH + the Unix-socket REST API: machine/boot/drive/network/vsock config, start/stop/pause/resume, snapshot/restore, precision kill_vmm + idempotent start_vmm, and host bootstrap (install Firecracker + guest kernel, setup_tap, build Ubuntu rootfs + agent).
- Ships the fc-install-firecracker, fc-bake-snapshot and fc-run-agent workflows.
@magistr/fc-task-server 2026.06.09.2
- Host<->guest task/result control-plane server (deploy / inject_task / collect_result / stop) for Claude Code agents in Firecracker microVMs.
Both gain a README + MIT LICENSE, repository metadata, unit tests (12 and 13 respectively, covering success and failure paths), and two labelled pre-flight checks: valid-ssh-host (policy) and host-reachable (live).
Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com
2026.06.09.18Jun 9, 2026
Modified 1 models. Added 1 workflows
2026.06.09.17Jun 9, 2026
2026.06.09.16Jun 9, 2026
2026.06.09.15Jun 9, 2026
2026.06.09.14Jun 9, 2026
2026.06.09.13Jun 9, 2026
2026.06.09.12Jun 9, 2026
2026.06.09.11Jun 9, 2026
Modified 1 models
2026.06.08.9Jun 8, 2026
2026.06.08.8Jun 8, 2026
Modified 1 models
2026.06.08.7Jun 8, 2026
06Stats
A
100 / 100
Downloads
1
Archive size
60.0 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
Repository
https://github.com/umag/swamp-workspace07Platforms
08Labels