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

Refresh docs for current VM workflows

Browse source 
Keep the user-facing docs aligned with the current Go control plane instead of the older one-VM-at-a-time and ambiguous rootfs rebuild flows.

Document concurrent multi-VM lifecycle and set commands, clarify that rebuilt images now include mise plus opencode, and spell out when make rootfs needs an explicit base image. Also update the repo guidelines so future changes keep those behaviors documented.
This commit is contained in:
Thales Maciel 2026-03-18 14:23:22 -03:00
parent 4e0132982d
commit 8ba920eda6
No known key found for this signature in database
GPG key ID: 33112E6833C34679
2 changed files with 23 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

2
AGENTS.md
View file

@ -14,6 +14,7 @@
- `./banger vm create --name testbox` creates and starts a VM.
- `./banger vm ssh testbox` connects to a running guest.
- `./banger vm stop testbox` stops a VM while preserving its disks.
- `./banger vm stop vm-a vm-b vm-c` and `./banger vm set --nat web-1 web-2` are supported; multi-VM lifecycle and `set` actions fan out concurrently through the CLI.
- `./banger tui` launches the terminal UI.
- `make test` runs `go test ./...`.
- `./verify.sh` runs the smoke test for the Go VM workflow.
@ -27,6 +28,7 @@
## Testing Guidelines
- Primary automated coverage is `go test ./...`.
- Manual verification for VM lifecycle changes: `./banger vm create`, confirm SSH access, then stop/delete the VM.
- Rebuilt images now include `mise` plus `opencode` by default; if you change guest provisioning, document whether users need to rebuild `./runtime/rootfs-docker.ext4` or another base image to pick it up.
- If you add a new operational workflow, document how to exercise it in `README.md`.
- For NAT changes, verify both guest outbound access and host rule cleanup, for example with `./verify.sh --nat`.

22
README.md
View file

@ -111,6 +111,14 @@ Update stopped VM settings:
banger vm set calm-otter --memory 2048 --vcpu 4 --disk-size 32G
```
Lifecycle and `set` actions also accept multiple VM refs and run them
concurrently:
```bash
banger vm stop calm-otter buildbox api-1
banger vm kill --signal KILL aa12bb34 cc56dd78
banger vm set --nat web-1 web-2 web-3
```
Launch the TUI:
```bash
banger tui
@ -146,7 +154,7 @@ Useful config keys:
- `firecracker_bin`
- `ssh_key_path`
- `namegen_path`
- `customize_script`
- `customize_script` (manual helper compatibility; `banger image build` is Go-native)
- `default_rootfs`
- `default_base_rootfs`
- `default_kernel`
@ -174,6 +182,10 @@ Build a managed image:
banger image build --name docker-dev --docker
```
Rebuilt images install a pinned `mise` at `/usr/local/bin/mise`, activate it
for bash login and interactive shells, and install `opencode` through `mise`
by default.
Show or delete images:
```bash
banger image show docker-dev
@ -215,6 +227,12 @@ To rebuild the source-checkout default image in `./runtime/rootfs-docker.ext4`:
make rootfs
```
If your runtime bundle does not include `./runtime/rootfs.ext4`, pass an
explicit base image instead:
```bash
./make-rootfs.sh --base-rootfs /path/to/base-rootfs.ext4
```
If the package manifest changed and you want a fresh source-checkout image:
```bash
rm -f ./runtime/rootfs-docker.ext4 ./runtime/rootfs-docker.ext4.packages.sha256
@ -223,6 +241,8 @@ make rootfs
`make rootfs` expects a bootstrapped runtime bundle. If `./runtime/rootfs.ext4`
is not available, pass an explicit `--base-rootfs` to `./make-rootfs.sh`.
Existing VMs keep using their current image and disks; rebuilds only affect VMs
created from the rebuilt image afterward.
## Maintaining The Runtime Bundle
The checked-in [`runtime-bundle.toml`](/home/thales/projects/personal/banger/runtime-bundle.toml)