banger/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• cmd/banger and cmd/bangerd are the primary user-facing entrypoints.
• internal/ contains the daemon, CLI, RPC, storage, Firecracker, and system integration code.
• The VM lifecycle is now organized around daemon capabilities plus a structured guest-config builder. New host-integrated VM features should plug into that Go path instead of adding more one-off branches through internal/daemon/vm.go.
• customize.sh, make-rootfs.sh, and interactive.sh remain as manual rootfs/customization helpers; normal VM lifecycle, NAT, .vm DNS, and daemon-driven image builds are handled by the Go control plane.
• Source checkouts use a generated ./runtime/ bundle for Firecracker, kernels, modules, rootfs images, and helper copies. Bundle defaults come from ./runtime/bundle.json when present. Those runtime artifacts are not meant to be tracked directly in Git.
• The daemon keeps state under XDG directories rather than the old repo-local state/ layout.

Build, Test, and Development Commands

• make build builds ./banger, ./bangerd, and the bundled ./runtime/banger-vsock-agent guest helper.
• make bench-create benchmarks vm create and first-SSH readiness on the current host.
• make runtime-bundle bootstraps ./runtime/ from the archive referenced by RUNTIME_MANIFEST; the checked-in runtime-bundle.toml is only a template.
• make void-kernel downloads and stages a Void linux6.12 kernel under ./runtime/void-kernel, including extracted vmlinux, raw vmlinuz, a matching generated initramfs, config, and matching modules.
• make rootfs-void builds an experimental local-only x86_64-glibc Void rootfs plus work-seed under ./runtime/; it prefers staged ./runtime/void-kernel modules when present, but does not replace the default Debian path or teach banger image build about Void.
• make verify-void registers void-exp and runs the normal smoke test against that image.
• banger validates required host tools per command and reports actionable missing-tool errors; do not assume one workstation's package set.
• ./banger vm create --name testbox creates and starts a VM.
• ./banger vm create now blocks until the guest reaches the daemon's default readiness checks and shows live progress stages on TTY stderr while it waits.
• ./banger vm ssh testbox connects to a running guest using the runtime bundle SSH key and reminds the user if the VM is still running when the session exits.
• ./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 doctor reports runtime bundle, host tool, feature, and image-build readiness from the same Go checks used by the daemon.
• ./banger image register --name local --rootfs /abs/path/rootfs.ext4 creates or updates an unmanaged image record without changing the default image config; use it for experimental guest iteration paths such as Void.
• bangerd now also serves a localhost web UI on http://127.0.0.1:7777 by default unless web_listen_addr = "" disables it; the UI uses server-rendered templates, polls async VM/image operations, and keeps image path selection on the host via a server-side file picker.
• make test runs go test ./....
• ./verify.sh runs the smoke test for the Go VM workflow.

Coding Style & Naming Conventions

• Go code should stay small, direct, and standard-library-first unless there is a clear reason otherwise.
• Shell helpers use Bash with set -euo pipefail; keep remaining shell scripts strict and explicit.
• Prefer lowercase filenames with short descriptive names.
• Use gofmt for Go formatting; no extra formatter is configured for shell files.

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.
• For host-integration changes, run ./banger doctor as a quick readiness check before the live VM smoke.
• The web UI follows the same sudo model as the CLI path: bangerd stays unprivileged and privileged writes only work when sudo -v is already warm or sudo is passwordless.
• Rebuilt images now include mise, opencode, a host-reachable default opencode server service on guest TCP port 4096, tmux-resurrect/tmux-continuum defaults for root, and the banger-vsock-agent service used by the SSH reminder and guest health-check path; if you change guest provisioning, document whether users need to rebuild ./runtime/rootfs-docker.ext4 or another base image to pick it up.
• The experimental Void rootfs path now includes the repo's basic dev baseline plus Docker and Compose, alongside boot, SSH, a guest network bootstrap sourced from the kernel ip= cmdline, the vsock HTTP health agent, pinned mise plus opencode for root, the default host-reachable opencode server service on guest TCP port 4096, a bash root shell while leaving /bin/sh alone, and the /root work-seed. When ./runtime/void-kernel/ exists, the Void image registration path expects a complete staged Void kernel, initramfs, and modules tree and points void-exp at it. Keep further baked-in tooling deliberate and user-driven.
• Rebuilt images also emit a work-seed.ext4 sidecar used to speed up future VM creates. Older managed images may take one slower create to refresh seeded SSH access before they rejoin the fast path. If you touch /root provisioning, verify both the rootfs and the work-seed output.
• The daemon may keep idle TAP devices in a pool for faster creates. Smoke tests should treat tap-pool-* devices as reusable capacity, not cleanup leaks.
• 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.

Commit & Pull Request Guidelines

• Git history uses short, imperative subjects.
• Prefer a real commit body when the change affects lifecycle behavior, storage semantics, or host integration.
• PRs should call out runtime requirements, migration impact, and any host-side verification performed.

Security & Configuration Tips

• The VM workflow requires sudo and /dev/kvm access; do not commit secrets.
• id_ed25519 lives inside the runtime bundle; rotate or replace it before publishing a shared bundle.