banger/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• run.sh is the primary launcher script; it builds the per-VM state and configures Firecracker over the local API socket.
• firecracker, vmlinux, and rootfs.ext4 are runtime artifacts required to boot the guest.
• state/ is created at runtime to store per-VM sockets, logs, and metadata (safe to delete when no VMs are running).
• firecracker.log is produced by Firecracker; additional per-VM logs live under state/vm-*/.

Build, Test, and Development Commands

• ./run.sh launches a VM using Firecracker, sets up a bridge/TAP device, and prints the guest IP plus SSH command.
• ssh -i "./id_ed25519" root@<guest_ip> connects to the guest once it boots.
• reboot (inside the guest) shuts down the VM.
• There is no build step in this repo; binaries and images are checked in.

Coding Style & Naming Conventions

• Shell scripts use Bash with set -euo pipefail; keep new scripts strict and explicit.
• Indentation is two spaces in run.sh; match existing formatting and quoting style.
• Filenames are short and descriptive (e.g., run.sh, rootfs.ext4). Prefer lowercase with dashes or dots.
• No formatter or linter is configured; keep changes small and readable.

Testing Guidelines

• No automated test framework is present.
• Manual verification: run ./run.sh, confirm the guest boots, and verify SSH access.
• If adding tests, document how to run them in this file and keep them self-contained.

Commit & Pull Request Guidelines

• Git history uses short, informal commit summaries (e.g., "ignore", "Document expected log noise").
• Prefer imperative, single-line subjects; keep them under ~50 characters when possible.
• PRs should describe the change, list any new runtime requirements, and include logs or screenshots if behavior changes.

Security & Configuration Tips

• The script requires sudo and /dev/kvm access; avoid committing secrets or private keys.
• id_ed25519 is a local SSH key for the guest; rotate or replace it if sharing the repository.