docs: DNS routing guide; README aimed at common users

Adds docs/dns-routing.md covering how `<vm>.vm` resolution works:
auto-configuration on systemd-resolved hosts (what the daemon
already does), and per-resolver recipes for dnsmasq /
NetworkManager+dnsmasq / /etc/resolv.conf / macOS `/etc/resolver/`
/ WSL. Plus verification via `dig @127.0.0.1 -p 42069` and
troubleshooting for the common failure modes.

README reshape: lead with the three things a common user needs —
quick start, what `vm run` does, where to put hostnames + image +
config — and push the rest to docs. `vm create` / OCI `image pull`
/ `image register` / workspace-and-session primitives are all still
documented, just under docs/advanced.md where they're not in the
first-time reader's way. Web UI and unnecessary implementation
notes dropped; the "further reading" section at the bottom
enumerates the five docs pages so nothing becomes hard to find.

README shrinks from 208 → 158 lines.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-18 17:24:50 -03:00

4.9 KiB

Raw Blame History

banger

One-command development sandboxes on Firecracker microVMs.

Quick start

make install
banger vm run --name sandbox

That's it. 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, 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), and banger-vsock-agent (companion, under $PREFIX/lib/banger/).

`vm run`

One command, four common shapes:

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, exits with its status
banger vm run --rm -- script.sh        # ephemeral: VM is deleted on exit

Bare mode gives you a clean shell.
Workspace mode (path given) 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 — or pass --rm so the VM auto-deletes once the session / command exits.

--branch and --from apply only to workspace mode. --rm skips the delete when the initial ssh wait times out, so a wedged sshd leaves the VM alive for banger vm logs inspection.

Hostnames: reaching `<vm>.vm`

banger's daemon runs a DNS server for the .vm zone. With host-side DNS routing you can ssh root@sandbox.vm or curl http://sandbox.vm:3000 from anywhere on the host — no copy-pasting guest IPs. On systemd-resolved hosts this is auto-wired; everywhere else there's a short recipe. See docs/dns-routing.md.

Image catalog

banger image pull <name> fetches a pre-built bundle from the embedded catalog. vm run calls this for you on demand.

Today's catalog:

Name	What it is
`debian-bookworm`	Debian 12 slim + sshd + docker + dev tools

See docs/image-catalog.md for the bundle format and how to publish a new entry.

Config

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

Most commonly set:

default_image_name — image used when --image is omitted (default 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).

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

`file_sync` — host → guest file copies

[[file_sync]]
host = "~/.aws"          # whole directory, recursive
guest = "~/.aws"

[[file_sync]]
host = "~/.config/gh/hosts.yml"
guest = "~/.config/gh/hosts.yml"

[[file_sync]]
host = "~/bin/my-script"
guest = "~/bin/my-script"
mode = "0755"            # optional; default 0600 for files

Runs at vm create time. Each entry copies host → guest onto the VM's work disk (mounted at /root in the guest). Guest paths must live under ~/ or /root/.... Default is no entries — add the ones you want.

Advanced

The common path is vm run. Power-user flows (vm create, OCI pull for arbitrary images, image register, long-lived sessions) are documented in docs/advanced.md.

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.

The web UI (when enabled) binds 127.0.0.1 by default. Do not expose it to a shared network.

4.9 KiB Raw Blame History