CLI Reference

Global Flags

Every jerboa command accepts:

Endpoint resolution order:

1. --host
2. deprecated --socket
3. JERBOA_HOST
4. [daemon] endpoint in ~/.jerboa/config.toml
5. platform default

Defaults:

• Linux: unix:///var/run/jerboad.sock
• Windows: tcp://127.0.0.1:7890 as the configured default, but the client resolves and dials the dedicated WSL2 distro IP when auto-booting the daemon

Authentication token resolution:

1. JERBOA_AUTH_TOKEN
2. [daemon] token in ~/.jerboa/config.toml

Core VM Commands

jerboa snapshot

Local macOS Firecracker/HVF snapshots on named networks:

jerboa snapshot create <vm> <name>
jerboa snapshot restore <vm> <name>
jerboa snapshot ls --output json
jerboa snapshot inspect <name>
jerboa snapshot rm <name>

Creation pauses and resumes a running VM. Restore requires the same VM to be stopped and resumes its captured memory and ephemeral root disk in place. VMs with volumes and the default slirp network are rejected. Existing TCP connections do not survive; snapshots are not portable backups. See macOS snapshots for quotas, compatibility and recovery.

jerboa run <image>

Create and start a VM from:

• an image reference like hello:latest
• a direct disk image path on the daemon filesystem

Key flags:

Notes:

• --attach requests an opt-in framed VM.Attach stream: console bytes remain separate from a terminal result, so a failed VM makes the CLI exit nonzero. Older daemons still send raw console bytes and cannot report terminal status through attach. On ARM Firecracker, a nonzero guest exit is signaled through pvpanic and currently surfaces as a generic error (CLI status 1), not the guest’s exact exit code.
• Port publishing requires --network on Linux and Windows. On macOS, -p works without it.
• Every VM on a managed network gets a guest IP: --ip pins it, otherwise the daemon’s IPAM allocates the next free address from the network’s subnet.
• On Linux, how published ports reach the guest depends on jerboad --port-publish; see Published ports on Linux. TCP always works; UDP needs kernel NAT (the default where nftables is available). macOS forwards both.
• On Windows the published port lives inside the jerboa WSL2 distro. With WSL2’s default NAT networking it is reachable at the distro IP (the host from jerboa daemon status), not at localhost on the Windows host — set networkingMode=mirrored in %USERPROFILE%\.wslconfig for Docker-Desktop-style localhost publishing. See Getting Started.

jerboa ps

List VMs known to the daemon. The command help still says “running”, but the implementation prints the daemon registry, including stopped entries when present.

jerboa status

Summary view of daemon-side VM counts and restart/health state.

jerboa logs <id>

Print buffered serial console output.

Flag:

• -f, --follow: poll and stream appended output until the VM stops

When the output contains a known Nanos failure signature (popen failure, error loading shared library, no space left on device, …), an explanation of the cause and the fix is printed after the logs. The same detection runs on jerboa run --attach output. See Troubleshooting for the full catalogue.

jerboa inspect <id>

Return full VM detail as JSON.

jerboa stats <id>

Show runtime stats.

Flags:

• -w, --watch
• -i, --interval

jerboa stop <id>

Graceful stop by default. Idempotent: stopping a VM that is already stopped (for example a program that ran to completion and exited on its own) is a no-op that succeeds, matching docker stop.

Flag:

• --force: immediate kill

jerboa rm <id>

Remove a stopped VM from the daemon registry.

jerboa exec <id>

Send a signal through the daemon.

Flag:

• --signal, default SIGTERM

Image Commands

jerboa build <path>

Build an image from a static ELF or a source directory.

Key flags:

unikernel.toml is read automatically when present, or selected explicitly with -f/--file. Relevant [build] keys:

For lang = "raw", [program] path names the runtime binary resolved from package files; the program is executed from its real in-image path, so binaries that locate their installation prefix relative to their own executable (e.g. postgres, mysqld) and binaries with $ORIGIN-relative library paths resolve correctly. When [program] is omitted entirely, the program and its arguments are inherited from the ops package’s own package.manifest (Program/Args), so well-formed ops packages build with just pkgs = [...].

Before assembling the image the build runs preflight checks: the program must be a 64-bit Linux ELF for a supported architecture; if dynamically linked, its interpreter and the full recursive DT_NEEDED shared-library closure must resolve against the image contents; node/python entrypoints must be among the packed files. Errors abort the build with a fix hint; --no-preflight skips the checks. See Build Concepts for the background.

[env] keys are baked into the image environment (highest priority — they override env supplied by packages or the language driver).

[run] keys are baked into the image manifest and inherited by jerboa run unless overridden by a flag (precedence: run flag > [run] value > built-in default):

[[stages]] defines multi-stage builds: each stage has its own lang, entrypoint, args, and copy_from (stage, src, dst) directives; the final stage’s output becomes the image binary.

Build driver behavior to know:

• Go builds add -trimpath and -ldflags "-s -w" by default to reduce guest binary and image size. If custom build args include -ldflags, those args are appended after the defaults and take precedence.
• Node builds reinstall production dependencies when manifests, lockfiles, runtime version or host platform change, or when node_modules is missing. If package-lock.json exists, the driver uses npm ci --omit=dev --no-audit --no-fund; otherwise it uses npm install --omit=dev --no-audit --no-fund.
• Python builds cache dependency installs. pip install runs only when requirements.txt or the Python version changes, tracked by packages/.jerboa-deps-stamp. Delete packages/ or that stamp file to force a dependency reinstall. Changed dependencies are installed into a clean staging directory, then replace the old set only after installation succeeds. Removed requirements therefore disappear from the rebuilt image.

Newly built images reserve a 4 MiB embedded boot filesystem partition instead of the previous 12 MiB layout, so they are about 8 MiB smaller (for example, hello drops from about 16.6 MiB to about 8.1 MiB). Older images are unchanged; rebuild an image to get the smaller layout.

jerboa init [path]

Write a commented unikernel.toml scaffold into path (default .). The language is auto-detected from marker files (go.mod, Cargo.toml, package.json, pyproject.toml/requirements.txt); ambiguous or empty directories get the generic template. The generated file documents every field inline, including the raw-mode program-path pitfalls.

Flags:

init is a purely local command — it never contacts the daemon.

jerboa images

List images stored by the daemon.

jerboa rmi <ref>

Remove an image from the daemon store. Refused with an error if any VM (running or stopped) still references the image; remove those VMs first. This mirrors docker rmi and prevents leaving a VM pointing at a disk that no longer exists. Removing by digest removes all tags pointing to that image. Ambiguous digest prefixes are rejected.

jerboa sign <image>

Resolve the image through the daemon and sign its disk digest with the default Ed25519 key.

jerboa verify <image>

Resolve the image through the daemon, hash its actual disk contents, and verify the signature against that digest. run --verify enforce pins the verified digest; each hypervisor verifies the bytes while writing its private boot copy and starts the VM only if the digest matches.

Package Commands

jerboa pkg manages runtime packages used during builds.

Subcommands:

Supported package sources (--source, default ops):

• ops — the nanovms/ops ecosystem at repo.ops.city; refs are <namespace>/<name>:<version> (e.g. eyberg/postgresql:11.3.0)
• jerboa — the first-party index; also where pkg create and pkg from-docker store their local packages

pkg from-docker flags:

• --file <path> — the binary inside the image to package. Optional: when omitted, the program is derived from the image’s Entrypoint/Cmd and resolved on the container’s PATH. The shared-library closure is read from the image’s exported filesystem (no ldd/cat inside the image), so it works on scratch and distroless images too, and every file is stored at its real absolute in-image path. Images whose entrypoint is a shell script (docker-entrypoint.sh and friends) cannot be derived — there is no shell in a unikernel — so pass --file with the real binary the script eventually launches.

# redis is a shell-launcher image, so name the real binary with --file.
jerboa pkg from-docker redis:7.2 redis:7.2 --file /usr/local/bin/redis-server
# unikernel.toml: lang="raw", pkgs=["redis:7.2"], pkg_source="jerboa",
#                 [program] path="/usr/local/bin/redis-server"
jerboa build . --name redis

pkg create flags:

• --platform linux/arm64|linux/amd64 — inferred from ELF when omitted; an explicit mismatch fails.
• --program-path <guest-path> — destination of the program inside the guest.
• --map source=destination — additional file at an explicit guest path (repeatable).
• --libs — additional files at their basenames (repeatable).
• --description, --runtime — metadata.
• --missing-files — report static dependency analysis; missing dependencies fail creation.
• --sysroot <dir> — resolve the loader and libraries within this rootfs, preserving guest paths.

pkg from-docker and selection operations also accept --platform. Docker imports record the requested reference, immutable image ID and available repository digest. Local variants coexist and take precedence over the remote index. jerboa images inspect <ref> displays image platform and integrated package versions, hashes and provenance. See ARM64 package workflow for local sysroots, compatibility rules and reproducible Firecracker acceptance.

pkg load uses the root command’s endpoint and authentication configuration, including --host and JERBOA_HOST. Use --source jerboa for local packages. pkg push without --platform prefers the default platform, then a legacy package, then the sole downloaded variant; use the flag for explicit selection.

Network And DNS Commands

jerboa network create <name>

Flags:

• --subnet
• --driver (currently bridge)

jerboa network ls

jerboa network inspect <name>

jerboa network rm <name>

jerboa dns resolve <name>

jerboa dns resolve-all <name>

jerboa dns list

Each DNS command accepts --network where relevant.

Published ports on Linux

jerboad --port-publish selects how a published port (-p) reaches the guest. Every mode keeps a real listening socket on the host, so the port is reserved and WSL2 can mirror it.

Kernel NAT removes a userspace hop on every message. With a Redis guest on an x86 host, kernel NAT served about 45 % more requests than the proxy.

nat-lan is opt-in because it changes how the host firewall applies to published ports, exactly as Docker does for its own ports:

• Connections from other hosts are forwarded to the guest bridge, so they skip the host’s INPUT rules. A ufw deny 8080 does not block a port published with -p 8080:80; restrict it with a bind address (-p 127.0.0.1:8080:80) or leave the daemon in auto.
• jerboad accepts those forwarded connections, and only those (conntrack DNAT state, to and from jerboa-br*), with rules commented jerboa published ports: in iptables DOCKER-USER when Docker is set up or FORWARD otherwise, and in the forward chains of other nftables tables (nftables.service, firewalld). They are removed when the daemon stops and on its next start after a crash, and restored when ports are published after a firewall reload.
• Guests see the client’s real address instead of the host’s.

Connections from guests to a port published on the host keep using the proxy in every mode. On WSL2, kernel NAT is disabled and every mode uses the proxy.

Volume Commands

jerboa volume create <name>

Flags:

Create and seed in one step:

jerboa volume create pgdata --size 1G \
  --seed-pkg eyberg/postgresql:11.3.0 --src /db

jerboa volume seed <name>

Populate an existing volume with an initialized filesystem taken from one or more packages, so the data is present the first time the volume is mounted. Created volumes are empty; mounting an empty volume over a data directory shadows whatever the image baked there. Seeding writes the package files into the volume’s filesystem (via mkfs on the daemon) so the data persists across VM lifecycles.

The canonical use is making a database persistent: a package such as eyberg/postgresql ships a pre-initialized data directory (initdb cannot run inside a unikernel — it fork/execs helper processes, which Nanos does not support), which is seeded onto a volume and then mounted.

jerboa volume create pgdata --size 1G
jerboa volume seed pgdata --pkg eyberg/postgresql:11.3.0 --src /db
jerboa run postgresql -v pgdata:/db --network pgnet -p 5432:5432

Flags:

Notes:

• --src /db rebases the package’s /db contents to the volume root, so mounting the volume at /db (-v <name>:/db) restores them in place.
• Re-running volume seed reformats and re-populates the volume, discarding any data written since the last seed — use it to reset a volume to a clean state.

jerboa volume ls

jerboa volume inspect <name>

jerboa volume rm <name>

Volume removal and seeding are rejected while any VM references the volume, including stopped VMs. Remove those VMs first.

Compose Commands

jerboa compose up <file>

jerboa compose down <file>

jerboa compose ps <file>

jerboa compose logs <file> <service>

Current behavior to know:

• top-level volumes are auto-created on compose up
• declared networks are auto-created on compose up
• compose down stops and removes the stack’s service VMs (no stopped remnants left behind), and removes the networks it created
• compose down --volumes additionally removes volumes created by that stack
• each compose file has its own state, identified by its canonical path
• partial deployments retain state for cleanup; repeated compose down is safe
• compose logs is snapshot-only; there is no follow mode today
• a service health_check uses the same grammar as run --health-check: tcp:PORT or http:PORT:/path (e.g. "tcp:8080", "http:8080:/healthz")

Cluster Commands

jerboa node ls

Requires the daemon to run with --cluster-addr.

Kernel Commands

jerboa kernel check

jerboa kernel update

kernel update accepts -y, --yes to skip the confirmation prompt.

These manage the cached toolchain (mkfs, boot.img, kernel.img) independently of the CLI version. Both resolve the latest kernel from the signed release manifest at releases.jerboa.dev and verify each artifact against its recorded SHA-256; there is no GitHub fallback and no historical version selection.

Version Command

jerboa version

Read-only readout of the installed CLI and kernel versions alongside the latest published version of every component (CLI, kernel, daemon, distro, desktop) taken from the signed release manifest. It never installs anything: on Windows the toolset is updated through the Jerboa Desktop app; on Linux you reinstall the CLI/daemon yourself. (jerboa --version still prints just the CLI version.)

Add --channel beta to query the beta channel instead of stable.

Config Commands

jerboa config get <key>

jerboa config set <key> <value>

The command group currently exposes only one writable key:

• hypervisor: qemu or firecracker

The config file supports more fields than the CLI subcommand currently edits. The underlying schema in ~/.jerboa/config.toml also includes:

• [daemon] endpoint
• [daemon] distro
• [daemon] jerboad_path
• [daemon] token

Those are read by the codepath even though jerboa config set does not edit them yet.

With hypervisor = "qemu", the daemon automatically enables KVM when /dev/kvm is accessible by adding -enable-kvm -cpu host. If KVM is not available, QEMU falls back to TCG emulation and the daemon logs a warning. Firecracker still requires KVM.

Windows Daemon Commands

These commands exist only on Windows.

jerboa daemon install

Import the dedicated WSL2 distro. Before replacing an existing installation, the CLI downloads and validates the replacement and exports a recovery backup. The backup path is printed and retained if replacement fails. Local --rootfs archives are also validated before any unregister operation.

Flags:

• --rootfs <tarball>
• --force

jerboa daemon reinstall

Reimport the distro rootfs (fresh or newer). Unlike install --force, which destroys everything, --keep-data preserves your images, VMs, networks and volumes across the swap (exported before, restored after). The daemon is stopped and restarted around the reimport; the kernel toolchain cache is not preserved (it re-downloads on demand).

Flags:

• --rootfs <tarball> — use a local rootfs instead of downloading the release
• --keep-data — preserve images, VMs, networks and volumes across the reimport
• --hypervisor <qemu|firecracker> — hypervisor to run after restart

jerboa daemon uninstall

jerboa daemon start

jerboa daemon restart

jerboa daemon stop

jerboa daemon status

jerboa daemon logs

Daemon start/restart flag:

• --hypervisor qemu|firecracker

jerboa daemon logs flag:

• -f, --follow

The daemon runs as root inside the dedicated distro. The client persists rendezvous state in ~/.jerboa/daemon.json.

Native jerboad Flags

jerboad is the Linux daemon binary.

Observability and store flags (--metrics-addr, --ui-addr, --trace-addr, --log-format, --vm-log-max-bytes, --vm-store) are covered in more detail in Observability.

Current Command Surface

Root commands currently exposed by the built CLI:

• build
• compose
• config
• daemon (Windows only)
• dns
• exec
• images
• init
• inspect
• kernel
• logs
• network
• node
• pkg
• ps
• rm
• rmi
• run
• sign
• stats
• status
• stop
• verify
• version
• volume