TheDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/deeplethe/forkd/llms.txt
Use this file to discover all available pages before exploring further.
forkd binary is the single entry point for every operation in the forkd microVM runtime — from baking parent snapshots and forking children, to distributing warm snapshots via the Snapshot Hub, to diagnosing the host and benchmarking fork latency. All functionality is exposed as subcommands: forkd <subcommand> [flags]. There are no persistent global flags; every option is scoped to its subcommand.
Installation
Install the pre-built tarball (no Rust toolchain required):forkd and forkd-controller on your PATH. Verify the install with:
Subcommand index
| Command | Description | Common use |
|---|---|---|
quickstart | Zero-to-first-fork in one command. Preflights the host, heals missing setup with your consent, bakes a snapshot, forks N children. | First-time setup |
snapshot | Boot a parent VM and snapshot it to disk, or branch a running sandbox into a new tag via the daemon. | Creating parent snapshots |
snapshot-diff | Derive a new diff snapshot from a base tag by running an installer command in a transient sandbox. | Building snapshot chains |
fork | Fork N children from a tagged snapshot in parallel. | High-throughput sandbox fan-out |
exec | Run a command inside a live sandbox via the in-guest TCP agent. | Driving a running child VM |
ping | Ping the guest agent to verify it is responding. | Health checks |
eval | Evaluate a Python expression against the warmed PID-1 interpreter — no subprocess overhead. | Fast code execution |
parent build | Convert a Docker image into a writable ext4 rootfs. | Rootfs preparation |
run | One-shot sandbox: build rootfs, snapshot, fork one child, exec a command, then shut down. | Quick ad-hoc sandboxes |
from-image | Build a forkd snapshot from a Docker image in one pipeline step. | Automated snapshot creation |
rmi | Remove one or more snapshot tags from disk and the daemon registry. | Snapshot lifecycle |
snapshot-info | Show chain depth, parent lineage, dependents, and on-disk sizes for a snapshot. | Pre-delete inspection |
snapshot-compact | Flatten a chained snapshot into a new base snapshot with no parent edge. | Chain maintenance |
ls | List live sandboxes from the daemon. | Observability |
kill | Kill one or more sandboxes by ID, tag, or all. | Cleanup |
where | Print the snapshot data directory path. | Scripting |
pack | Pack a local snapshot into a portable .forkd-snapshot.tar.zst file. | Snapshot Hub distribution |
unpack | Unpack a .forkd-snapshot.tar.zst archive into a local snapshot tag. | Snapshot Hub consumption |
pull | Download and unpack a snapshot pack from a URL or <owner>/<name> hub short form. | Snapshot Hub consumption |
push | Pack a local snapshot and upload it to a presigned PUT URL. | Snapshot Hub publishing |
images | List local snapshots with sizes, memory footprint, and rootfs presence. | Local inventory |
doctor | Diagnose host setup across 17 checks and emit fix hints for each failure. | Host configuration |
bench | Probe a live daemon’s latency: spawn → exec → branch → fanout → cleanup. | Performance validation |
cleanup | Remove orphaned /tmp/forkd-{fork,parent,unpack,pull}-* work directories. | Temp file management |
workspace | Stateful long-lived sandboxes that survive suspend/resume across daemon restarts. | Persistent environments |
wp-bench | Exercise the UFFD_WP machinery on a synthetic memfd outside Firecracker — measures arm_duration and bulk-copy throughput. | v0.4 UFFD benchmarking |
Environment variables
Base URL for the forkd controller daemon. Used by
snapshot (with --from-sandbox), snapshot-diff, rmi, snapshot-info, snapshot-compact, ls, kill, doctor, bench, and workspace subcommands.Bearer token for the controller daemon. Must match the value in the daemon’s
--token-file. Set this instead of passing --daemon-token on every command.Path to the
vmlinux kernel image. Used as the default for --kernel in snapshot, from-image, and run. When unset, from-image searches ./vmlinux-6.1.141, ./vmlinux, /var/lib/forkd/kernels/vmlinux, and /usr/local/share/forkd/vmlinux in order.Host tap device name (e.g.
forkd-tap0). Used as the default for --tap in snapshot, from-image, and run. Create the tap device with sudo bash scripts/host-tap.sh.Path to the rootfs image. Used as the default for
--rootfs in forkd snapshot. Pass a .ext4 path for read-write or .squashfs for read-only. Required on the local-boot path unless --from-sandbox is set.Hub base URL used by
forkd pull when resolving <owner>/<name> short-form targets. When unset, forkd falls back to https://raw.githubusercontent.com/deeplethe/forkd/main/registry.json. Override to point at a self-hosted registry.XDG base directory. Snapshots are stored under
$XDG_DATA_HOME/forkd/snapshots/<tag>/. Override to relocate the snapshot store to a different volume.Directory where
forkd run and forkd from-image cache built rootfs .ext4 files. Re-running with the same image skips the Docker → ext4 step when the file is already present.Tag format rules
Every snapshot tag must match the pattern[A-Za-z0-9_][A-Za-z0-9._-]{0,63}:
- Length: 1–64 characters.
- First character: must be a letter (
A-Z,a-z), digit (0-9), or underscore (_). Tags cannot start with.or-. - Subsequent characters: letters, digits,
.,_, or-. - No path separators:
/and\are rejected to prevent directory traversal when unpack reads a manifest tag.
forkd unpack manifest verifier — a malicious pack that declares tag = "../../etc/x" is rejected before any files are written.
Valid examples: pyagent, py-numpy, python_3.12, quickstart
Invalid examples: .hidden, -leading-dash, a/b, tag with spaces
Further reading
- Snapshot Commands —
snapshot,snapshot-diff,from-image,rmi,snapshot-info,snapshot-compact - Fork Commands —
fork,run,parent build,ls,kill,cleanup,doctor,bench,workspace,where,wp-bench - Sandbox Commands —
exec,eval,ping - Hub Commands —
pack,push,pull,unpack,images