banger/docs/config.md

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 > 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.

# ~/.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"