# Advanced flows

`banger vm run` covers the common sandbox case. This doc is for the
rest: scripting, arbitrary images, custom rootfs stacks, long-lived
guest processes.

Host-side assumption for everything below: the supported runtime model
is still the two-service `systemd` install:

- `bangerd.service` running as the owner user
- `bangerd-root.service` running as the privileged host helper

These advanced flows widen what you do with banger, not which host
init systems or privilege model are supported.

## `vm create` — the low-level primitive

Use when you want to provision without starting, or when you need to
script VM creation piecewise.

```bash
banger vm create --image debian-bookworm --name testbox --no-start
banger vm start testbox
banger vm ssh testbox
banger vm stop testbox
banger vm delete testbox
```

Sweep every non-running VM (stopped, created, error) with:

```bash
banger vm prune          # interactive confirmation
banger vm prune -f       # skip the prompt
```

`vm create` is synchronous by default, but on a TTY it shows live
progress until the VM is fully ready.

## `image pull <oci-ref>` — arbitrary container images

For images outside banger's 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 (setuid binaries, root-owned
config preserved), banger's guest agents are injected, and a first-boot
systemd service installs `openssh-server` via the guest's package
manager so the VM is reachable on first boot.

See [`docs/oci-import.md`](oci-import.md) for supported distros,
caveats, and the `internal/imagepull` design.

## `image register` — existing host-side stack

If you already have an ext4 rootfs, a kernel, optional initrd, and
optional modules as files on disk:

```bash
banger image register --name base \
  --rootfs /abs/path/rootfs.ext4 \
  --kernel-ref generic-6.12
```

You can mix `--kernel-ref` (a cataloged kernel) with `--rootfs` from
disk, or pass `--kernel /abs/path/vmlinux` for a one-off kernel.

For reproducible custom images, write a Dockerfile and publish it to
an image catalog. See [`docs/image-catalog.md`](image-catalog.md).

## Workspace primitive

`vm run ./repo` (see README) handles the common case. For a manual
flow against an already-running VM, `vm workspace prepare`
materialises a local git checkout into the guest:

```bash
banger vm workspace prepare <vm> ./other-repo --guest-path /root/repo
```

Default guest path is `/root/repo`; default mode is a shallow
metadata copy plus a tracked-files overlay. Untracked files are
skipped by default — pass `--include-untracked` to ship untracked
non-ignored files too. Pass `--dry-run` to list the exact file set
without touching the guest. For repositories with submodules, pass
`--mode full_copy`.

## Inspecting boot failures

When a VM's create flow errors ("ssh did not come up within 90s" or
similar), the VM is kept alive for inspection:

- `banger vm logs <name>` — the firecracker serial console output,
  the best window into a stuck boot (systemd unit failures, kernel
  panics, missing modules).
- `banger vm ports <name>` — what's listening in the guest. Works as
  long as banger's vsock agent has come up, even if SSH is wedged.
- `banger vm show <name>` — daemon-side state (IP, PID, overlay
  paths).

`--rm` on `vm run` intentionally does NOT fire when the initial ssh
wait times out, so the VM stays around for post-mortem.