banger/README.md

banger

One-command development sandboxes on Firecracker microVMs.

Quick start

make install
banger vm run --name sandbox

banger vm run auto-pulls the default golden image (Debian bookworm with systemd, sshd, Docker CE, git, jq, mise, and the usual dev tools) and kernel from the embedded catalog if they aren't already local, creates a VM, starts it, and drops you into an interactive ssh session. First run takes a couple minutes (bundle download); subsequent vm runs are seconds.

Requirements

• Linux with /dev/kvm
• sudo
• Firecracker on PATH, or firecracker_bin set in config
• host tools checked by banger doctor

Build + install

make install

Installs:

• banger (CLI)
• bangerd (daemon, auto-starts on first CLI call)
• banger-vsock-agent (companion, under $PREFIX/lib/banger/)

vm run

One command, three modes:

banger vm run                          # bare sandbox — drops into ssh
banger vm run ./repo                   # workspace at /root/repo — drops into ssh
banger vm run ./repo -- make test      # workspace + run command, exit with its status

• Bare mode gives you a clean shell.
• Workspace mode (with a path) copies the repo's tracked + untracked non-ignored files into /root/repo and kicks off a best-effort mise tooling bootstrap from the repo's .mise.toml / .tool-versions. Log: /root/.cache/banger/vm-run-tooling-<repo>.log.
• Command mode (-- <cmd>) runs the command in the guest; exit code propagates through banger.

Disconnecting from an interactive session leaves the VM running. Use vm stop / vm delete to clean up.

--branch and --from apply only to workspace mode.

Image catalog

banger image pull <name> resolves <name> in the embedded catalog and fetches a pre-built bundle (rootfs.ext4 + manifest, tar+zstd). The kernel referenced by the manifest auto-pulls too. vm run calls this for you on demand.

Today's catalog:

Name	Distro	Kernel
debian-bookworm	Debian 12 slim + sshd + docker + dev tools	generic-6.12

The catalog ships embedded in the banger binary. See docs/image-catalog.md for maintenance.

Power-user flows

Skip this section if vm run is enough.

vm create — low-level primitive

For scripting or --no-start provisioning:

banger vm create --image debian-bookworm --name testbox --no-start
banger vm start testbox
banger vm ssh testbox
banger vm stop testbox

image pull <oci-ref> — arbitrary container images

For images outside the catalog, pull from any OCI registry:

banger image pull docker.io/library/alpine:3.20 --kernel-ref generic-6.12

Layers are flattened, ownership is fixed, banger's guest agents are injected, and a first-boot service installs openssh-server via the guest's package manager. See docs/oci-import.md for supported distros and caveats.

image register — existing host-side stack

banger image register --name base \
  --rootfs /abs/path/rootfs.ext4 \
  --kernel-ref generic-6.12

image build --from-image — derived images

banger image build --name devbox --from-image debian-bookworm --docker

Spins up a transient VM from a base image, applies opinionated customisation (mise, claude, pi, tmux plugins), saves a new managed image.

Workspace + session primitives

Long-lived guest commands managed by the daemon, attachable over a local Unix socket bridge:

banger vm workspace prepare <vm> ./other-repo --guest-path /root/repo
banger vm session start <vm> --name planner --cwd /root/repo --stdin-mode pipe -- pi --mode rpc
banger vm session attach <vm> planner
banger vm session logs <vm> planner --stream stderr
banger vm session stop <vm> planner

For ACP-aware host tooling: banger vm acp <vm> bridges stdio to guest opencode acp over SSH.

Config

Config lives at ~/.config/banger/config.toml. All keys optional.

Commonly set:

• default_image_name — image to use when --image is omitted (defaults to debian-bookworm, auto-pulled from the catalog if not local).
• ssh_key_path — host SSH key; if unset banger creates ~/.config/banger/ssh/id_ed25519.
• firecracker_bin — override the auto-resolved PATH lookup.
• web_listen_addr — experimental web UI (default 127.0.0.1:7777; set to "" to disable).
• Network: bridge_name, bridge_ip, cidr, tap_pool_size, default_dns.

Full key list in internal/config/config.go.

Credential sync

If these host auth files exist, banger syncs them into the guest at VM start:

Host	Guest
~/.local/share/opencode/auth.json	/root/.local/share/opencode/auth.json
~/.claude/.credentials.json	/root/.claude/.credentials.json
~/.pi/agent/auth.json	/root/.pi/agent/auth.json

Host-side changes take effect after the VM restarts. Session/history directories are not copied.

Web UI (experimental)

bangerd serves a local web UI at http://127.0.0.1:7777 by default. Convenient for local observability, not a stable interface. Do not expose the listen address to a shared network.

Security

Guest VMs are single-user development sandboxes, not multi-tenant servers. Every provisioned image is configured with:

PermitRootLogin yes
StrictModes no

The host SSH key is the only authentication mechanism, no password auth is enabled, and VMs are reachable only through the host bridge network (172.16.0.0/24 by default). Do not expose the bridge interface or guest IPs to an untrusted network.

Notes

• Managed image delete removes the daemon-owned artifact dir.
• Layer blob cache for OCI pulls lives under ~/.cache/banger/oci/.
• Image bundle cache doesn't exist — bundles are extracted directly into the image store; re-pulls download fresh.