# Config reference

banger reads `~/.config/banger/config.toml` at daemon start; every key is
optional. Defaults are applied for anything you omit. Path: see also
[docs/privileges.md](privileges.md) > Filesystem mutations.

---

## Top-level keys

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `log_level` | string | `"info"` | Daemon log verbosity; overridden at runtime by `BANGER_LOG_LEVEL`. Accepted values are the standard slog levels: `debug`, `info`, `warn`, `error`. |
| `firecracker_bin` | string | auto-detected from `PATH` | Path to the `firecracker` binary. Accepts absolute paths or `~/`-anchored paths. If unset, banger resolves `firecracker` on `PATH` at startup. |
| `jailer_bin` | string | `"/usr/bin/jailer"` | Path to the Firecracker `jailer` binary used to sandbox each VM process. |
| `jailer_enabled` | bool | `true` | When `false`, VMs are launched directly without the jailer. Disabling the jailer removes the seccomp/namespace sandbox; only for debugging or environments where jailer is unavailable. |
| `jailer_chroot_base` | string | `"<state_dir>/jail"` | Base directory under which the jailer creates per-VM chroot trees. Must be on the same filesystem as the image store to allow hard-linking without crossing device boundaries. |
| `ssh_key_path` | string | `"<state_dir>/ssh/id_ed25519"` (auto-generated) | Host SSH key used to reach guest VMs. Accepts absolute paths or `~/`-anchored paths; `~/foo` expands against `$HOME`. Relative paths are rejected. If unset, banger auto-generates an ed25519 keypair on first start. |
| `default_image_name` | string | `"debian-bookworm"` | Image used when `--image` is omitted from `vm run` / `vm create`. The named image is auto-pulled from the catalog if not already local. |
| `auto_stop_stale_after` | duration | `"0"` (disabled) | If non-zero, the daemon automatically stops VMs that have not been touched within this duration. Accepts Go duration strings (`"24h"`, `"2h30m"`). |
| `stats_poll_interval` | duration | `"10s"` | How often the daemon collects CPU and memory stats for running VMs. Accepts Go duration strings (`"30s"`, `"1m"`). |
| `bridge_name` | string | `"br-fc"` | Name of the Linux bridge device banger creates for the VM network. |
| `bridge_ip` | string | `"172.16.0.1"` | IP address assigned to the host side of the bridge (the gateway VMs see). |
| `cidr` | string | `"24"` | Prefix length for the VM subnet (combined with `bridge_ip` to define the network, e.g. `172.16.0.0/24`). |
| `tap_pool_size` | int | `4` | Number of TAP network devices pre-allocated in the pool. Increase if you routinely run more concurrent VMs than this value. |
| `default_dns` | string | `"1.1.1.1"` | DNS resolver address advertised to guest VMs via DHCP. |

---

## `[vm_defaults]`

The optional `[vm_defaults]` block sets the sizing floor for every new VM.
When a key is omitted (or zero), banger falls back to host-derived heuristics
and then to built-in constants. `banger doctor` prints the effective defaults
with their provenance.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `vcpu` | int | host heuristic (≈ `cpus/4`, max 4) | Number of vCPUs assigned to each new VM. Must be ≥ 0; 0 means "let banger decide." |
| `memory_mib` | int | host heuristic (≈ `ram/8`, max 8192) | RAM in mebibytes assigned to each new VM. Must be ≥ 0; 0 means "let banger decide." |
| `disk_size` | string | `"8G"` | Size of the per-VM work disk. Accepts K/M/G suffixes (`"16G"`, `"512M"`). Maximum is 128 GiB. |
| `system_overlay_size` | string | `"8G"` | Size of the copy-on-write overlay layered over the read-only root filesystem. Accepts K/M/G suffixes. Maximum is 128 GiB. |

---

## `[[file_sync]]`

Each `[[file_sync]]` entry copies a file or directory from the host into
the VM's work disk at `vm create` time. You may declare any number of
entries; the default is none. Missing host paths are skipped with a warning
rather than failing the create.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `host` | string | **required** | Source path on the host. Must be absolute or `~/`-anchored, and must resolve inside the installed owner's home directory. Top-level symlinks are followed only when their target stays inside that home. |
| `guest` | string | **required** | Destination path inside the VM. Must be absolute or `~/`-anchored, and must resolve under `/root` (the work disk mount point). |
| `mode` | string | `"0600"` for files, `"0755"` for directories | Unix permission bits applied to the destination. Must be a 3- or 4-digit octal string (`"0755"`, `"600"`). |

---

## Example

A fully annotated `config.toml` showing every section. Omit any key to keep
the built-in default.

```toml
# ~/.config/banger/config.toml

# ── Binaries ──────────────────────────────────────────────────────────────────

# Override the auto-resolved firecracker binary.
# firecracker_bin = "/usr/local/bin/firecracker"

# Override the default jailer binary path.
# jailer_bin = "/usr/bin/jailer"

# Disable the jailer (removes seccomp/namespace sandbox — debug only).
# jailer_enabled = false

# Base directory for per-VM jailer chroot trees.
# jailer_chroot_base = "/var/lib/banger/jail"

# ── Identity ──────────────────────────────────────────────────────────────────

# SSH key used to reach VMs. Auto-generated as an ed25519 key if unset.
# ssh_key_path = "~/.local/state/banger/ssh/id_ed25519"

# Default image for `vm run` / `vm create` when --image is omitted.
# default_image_name = "debian-bookworm"

# ── Logging ───────────────────────────────────────────────────────────────────

# Daemon log verbosity: debug | info | warn | error
# log_level = "info"

# ── Lifecycle ─────────────────────────────────────────────────────────────────

# Automatically stop VMs not touched within this window. 0 disables auto-stop.
# auto_stop_stale_after = "24h"

# How often to collect CPU/memory stats for running VMs.
# stats_poll_interval = "10s"

# ── Networking ────────────────────────────────────────────────────────────────

# Name of the Linux bridge device created for the VM network.
# bridge_name = "br-fc"

# Host-side IP address of the bridge (the gateway VMs see).
# bridge_ip = "172.16.0.1"

# Subnet prefix length combined with bridge_ip.
# cidr = "24"

# TAP device pool size — increase if you run more concurrent VMs than this.
# tap_pool_size = 4

# DNS resolver advertised to guests.
# default_dns = "1.1.1.1"

# ── VM sizing defaults ────────────────────────────────────────────────────────

[vm_defaults]
# vCPUs per VM. 0 = let banger decide from host heuristics.
vcpu = 2

# RAM in MiB per VM. 0 = let banger decide from host heuristics.
memory_mib = 2048

# Work disk size (K/M/G suffix). Max 128G.
disk_size = "8G"

# Copy-on-write overlay over the root filesystem (K/M/G suffix). Max 128G.
system_overlay_size = "8G"

# ── Host → guest file copies ──────────────────────────────────────────────────

# Copy an entire directory (recursive).
[[file_sync]]
host  = "~/.aws"
guest = "~/.aws"

# Copy a single file with explicit permissions.
[[file_sync]]
host  = "~/.config/gh/hosts.yml"
guest = "~/.config/gh/hosts.yml"

# Copy a script and make it executable.
[[file_sync]]
host  = "~/bin/my-script"
guest = "~/bin/my-script"
mode  = "0755"
```