thaloco/banger
1
Fork 0
Code Pull requests Releases Packages Activity Actions

docs: DNS routing guide; README aimed at common users

Browse source 
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>
This commit is contained in:
Thales Maciel 2026-04-18 17:24:50 -03:00
parent 2584f94828
commit 88425fb857
No known key found for this signature in database
GPG key ID: 33112E6833C34679
3 changed files with 296 additions and 109 deletions
Download patch file Download diff file Expand all files Collapse all files

169
README.md
View file

@ -9,12 +9,11 @@ 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 run`s are seconds.
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 run`s are seconds.
## Requirements
@ -29,131 +28,78 @@ subsequent `vm run`s are seconds.
make install
```
Installs:
- `banger` (CLI)
- `bangerd` (daemon, auto-starts on first CLI call)
- `banger-vsock-agent` (companion, under `$PREFIX/lib/banger/`)
Installs `banger` (CLI), `bangerd` (daemon, auto-starts on first
CLI call), and `banger-vsock-agent` (companion, under
`$PREFIX/lib/banger/`).
## `vm run`
One command, three modes:
One command, four common shapes:
```bash
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
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 (with a path) copies the repo's tracked + untracked
- **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` /
`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`.
- **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.
`--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.
`--rm` delete is skipped 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`](docs/dns-routing.md).
## 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.
`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 | Distro | Kernel |
|------|--------|--------|
| `debian-bookworm` | Debian 12 slim + sshd + docker + dev tools | `generic-6.12` |
| Name | What it is |
|------|-----------|
| `debian-bookworm` | Debian 12 slim + sshd + docker + dev tools |
The catalog ships embedded in the banger binary. See
[`docs/image-catalog.md`](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:
```bash
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:
```bash
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`](docs/oci-import.md)
for supported distros and caveats.
### `image register` — existing host-side stack
```bash
banger image register --name base \
--rootfs /abs/path/rootfs.ext4 \
--kernel-ref generic-6.12
```
For custom images, write a Dockerfile and either publish to the
catalog (see `docs/image-catalog.md`) or pull it via the OCI path.
### Workspace + session primitives
Long-lived guest commands managed by the daemon, attachable over a
local Unix socket bridge:
```bash
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
```
See [`docs/image-catalog.md`](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.
Commonly set:
Most commonly set:
- `default_image_name` — image to use when `--image` is omitted
(defaults to `debian-bookworm`, auto-pulled from the catalog if not
- `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
- `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`.
- `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/directory copies, declared per-user in
`~/.config/banger/config.toml`:
### `file_sync` — host → guest file copies
```toml
[[file_sync]]
@ -167,22 +113,19 @@ guest = "~/.config/gh/hosts.yml"
[[file_sync]]
host = "~/bin/my-script"
guest = "~/bin/my-script"
mode = "0755" # optional; defaults to 0600 for files
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/...`. Host-side changes take effect
after the next `vm create`. Missing host paths are a soft skip with
a warning in the daemon log.
must live under `~/` or `/root/...`. Default is no entries — add the
ones you want.
Default is no entries — add the ones you want.
## Advanced
## 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.
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`](docs/advanced.md).
## Security
@ -199,9 +142,17 @@ 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
The web UI (when enabled) binds `127.0.0.1` by default. Do not
expose it to a shared network.
- 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.
## Further reading
- [`docs/dns-routing.md`](docs/dns-routing.md) — resolving
`<vm>.vm` hostnames from the host.
- [`docs/image-catalog.md`](docs/image-catalog.md) — bundle format
and publishing.
- [`docs/kernel-catalog.md`](docs/kernel-catalog.md) — kernel
bundles.
- [`docs/oci-import.md`](docs/oci-import.md) — pulling arbitrary
OCI images.
- [`docs/advanced.md`](docs/advanced.md) — power-user flows.