banger/CHANGELOG.md

# Changelog

All notable changes to banger are documented here. The format is based
on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

The version line printed by `banger version` is the canonical reference
for what's installed; this file is the canonical reference for what
changed between versions.

## [Unreleased]

## [v0.1.0] - 2026-04-29

First public release. banger runs disposable development sandboxes as
Firecracker microVMs: each sandbox boots in a few seconds, gets its own
root filesystem and network, and exits on demand.

### Added

**Sandbox VMs**
- `banger vm run` boots a microVM, drops you into ssh, and tears it down
  on exit. Optional positional path ships a host repo into the guest;
  `-- cmd args` runs a command non-interactively and exits with its
  status.
- Long-lived VMs via `vm create` / `vm start` / `vm stop` /
  `vm restart` / `vm ssh` / `vm exec` / `vm logs` / `vm stats` /
  `vm ports` / `vm kill`. `vm list` and `ps` enumerate state;
  `vm prune` deletes every non-running VM.
- `vm workspace` ships a host repo into a guest and pulls diffs back.
- Per-VM cgroup-isolated firecracker process under jailer chroot;
  daemon restarts do not interrupt running guests.

**Images**
- `banger image pull <name>` pulls a curated rootfs+kernel bundle from
  the banger image catalog. `image pull <oci-ref>` pulls any OCI image.
- `image list` / `image show` / `image delete` / `image promote` /
  `image register` round out the lifecycle.
- `image cache` manages the OCI layer-blob cache.
- Concurrent pulls of the same image are coalesced; the first pull
  wins, the rest wait.

**Kernels**
- `banger kernel pull <name>` pulls a Firecracker-compatible kernel
  from the banger kernel catalog. `kernel list` / `kernel show` /
  `kernel rm` manage the local store.

**Host networking**
- Per-host bridge with NAT; per-VM tap device; deterministic IPv4
  assignment; iptables rules installed/removed with VM lifecycle.
- DNS routing: local resolver on `127.0.0.1:42069` answers queries
  for `<vm>.vm` so plain `ssh <vm>.vm` reaches the guest.
- `banger ssh-config` writes a one-time `~/.ssh/config` include so
  ssh, scp, and rsync resolve `<vm>.vm` from any terminal.

**System install**
- `sudo banger system install` installs an owner-mode daemon
  (`bangerd.service`) and a root-helper (`bangerd-root.service`) as
  systemd units. The owner daemon runs as the invoking user; only the
  root helper holds privilege, and only for a vetted set of operations.
- `system status` / `system restart` / `system uninstall` round out
  the lifecycle. `daemon` is a thin alias.
- `banger doctor` audits host readiness: architecture, CLI/install
  version drift, state store, host runtime, vm lifecycle prerequisites,
  vsock guest agent, vm defaults, ssh shortcut, /root work disk, DNS,
  NAT, firecracker binary version, systemd units, socket permissions,
  helper unit hardening directives.

**Self-update**
- `banger update` downloads, verifies, and installs newer releases
  from the public manifest. Flow: fetch manifest, refuse if any VM
  operation is in flight, download tarball + `SHA256SUMS` +
  `SHA256SUMS.sig`, verify the cosign signature against the embedded
  public key, verify the tarball hash, stage to a scratch dir, run
  `bangerd --check-migrations` against the staged binary, atomically
  swap the three banger binaries, restart the systemd units, run
  `banger doctor`, finalise the install record.
- Pre-restart abort and post-restart auto-rollback both restore the
  previous install on failure.
- `banger update --check` reports whether a newer release is
  available without applying it; `--to vX.Y.Z` pins a specific
  version; `--dry-run` prints the plan; `--force` skips the
  in-flight-op refusal.

**Trust model**
- Every release is cosign-signed. The public key is embedded in the
  banger binary at build time; the signed payload is `SHA256SUMS`,
  which in turn covers the release tarball. Verification uses the
  Go standard library (`crypto/ecdsa.VerifyASN1`); cosign is needed
  only for *signing*, not for verification.
- The release manifest URL is hardcoded into the binary so a
  compromised daemon config cannot redirect the updater to a different
  bucket.

**CLI surface**
- Top-level: `vm`, `ps`, `image`, `kernel`, `ssh-config`, `system`,
  `daemon`, `doctor`, `update`, `version`, `completion`.
- `banger version` reports the version, commit SHA, and build
  timestamp baked in via ldflags at release-build time.

### Compatibility

- The host-side and guest-side vsock agent protocol is informally
  stable across **patch** versions (v0.1.x). Minor-version bumps
  (v0.2.x) may change it; existing VMs created against an older
  minor will need to be re-pulled. `banger doctor` warns when a
  running VM's agent is older than the daemon expects but does not
  block lifecycle operations.
- The on-disk store schema is forward-only. Downgrading the binary
  against a database written by a newer binary is unsupported; the
  updater detects this via `bangerd --check-migrations` and refuses
  the swap rather than starting up against an incompatible store.
- Linux only. amd64 only. KVM required.

[Unreleased]: https://git.thaloco.com/thaloco/banger/compare/v0.1.0...HEAD
[v0.1.0]: https://git.thaloco.com/thaloco/banger/releases/tag/v0.1.0