Box Config

Declaratively provision a Lager Box’s container — USB device permissions, packages, mounts, environment, and more

lager box config manages a declarative configuration for a Lager Box’s container. You describe what the box should have — USB device permissions (udev rules), apt packages, bind mounts, environment variables, pip/cargo/npm packages, sysctl values — and then apply puts it into effect. The configuration persists across container restarts and box updates.

Syntax

lager box config COMMAND [OPTIONS]

Global Options

Option	Description
--box TEXT	Lagerbox name or IP address
--help	Show help message and exit

How It Works

Editing the config and putting it into effect are two separate steps:

1. Change the config — udev add, apt add, mount add, env set, etc. These only edit the stored config; nothing happens on the box yet.
2. Apply it — lager box config apply validates the config and restarts (“bounces”) the container so the changes take effect. Host-side pieces (apt packages, udev rules, sysctl) are installed on the box host during apply; everything else is mounted into the fresh container.

lager box config udev add 1209:0001 --box my-lager-box   # 1. edit
lager box config apply --box my-lager-box                # 2. apply

Commands

Lifecycle

Command	Description
show	Print the current config
status	One-line summary of config state
diff	Show pending changes vs. the last applied config
validate	Validate the current config
apply	Validate, then restart the container so the new config takes effect
init	Create the config with defaults
reset	Erase the config to empty
restart	Restart the container without changing the config
repair	Restore the config from the last applied snapshot and restart
edit	Open the config in $EDITOR
import / export	Replace the config from / write the config to a local JSON file
copy	Copy one box’s config to another box
audit	Show recent config changes recorded on the box

Provisioning

Group	Description
udev	Host udev rules granting USB device access (by vid:pid)
apt	Host-side apt packages
mount	Host-to-container bind mounts
volume	Named docker volumes attached to the container
env	Container environment variables
pip / cargo / npm	In-container language packages
sysctl	Host sysctl values persisted across reboots

---

Command Reference

udev

Grant a USB device read/write access from inside the container, by USB vendor/product id. Use this when a freshly-plugged device is owned by root and a tool inside the container can’t open it (for example dfu-util failing with “No DFU capable USB device available”).

lager box config udev add VID:PID [VID:PID ...] [--mode 0666] [--usbtmc]
lager box config udev list [--json]
lager box config udev remove VID:PID [VID:PID ...]

Option	Description
--mode TEXT	Octal device-node permission mode (default 0666)
--usbtmc	Also emit the usbtmc driver-unbind rule, required for SCPI/USB‑TMC instruments accessed via PyVISA/libusb

VID and PID are 4 hex digits each. A 0x prefix and uppercase are accepted and normalized (so 0x1AB1:0E11 becomes 1ab1:0e11). Re-adding the same vid:pid updates it in place.

# Let dfu-util open a generic test device, then apply
lager box config udev add 1209:0001 --box my-lager-box
lager box config apply --box my-lager-box

# A SCPI power supply that also needs the usbtmc driver unbound
lager box config udev add 1ab1:0e11 --usbtmc --box my-lager-box
lager box config apply --box my-lager-box

On apply, the rules are installed to /etc/udev/rules.d/99-lager-user.rules on the box host and udev is reloaded, so existing devices pick up the new permissions.

reset

Erase the config to a truly empty state. Unlike init (which re-seeds the default box-tools volume), reset clears everything — a clean slate.

lager box config reset [--yes] [--apply]

Option	Description
--yes	Skip the confirmation prompt
--apply	Also restart the container so you get a fresh, empty container in one step

# Wipe the config and bring up a fresh container
lager box config reset --apply --yes --box my-lager-box

restart

Restart the container without changing the config — a fresh container with the same setup. Useful for test isolation between runs. Unlike apply, it restarts unconditionally (it does not skip when the config is unchanged).

lager box config restart [--yes] --box my-lager-box

apply

Validate the config and restart the container so changes take effect.

lager box config apply [OPTIONS] --box my-lager-box

Option	Description
--yes	Skip the confirmation prompt
--force	Restart even if the config is unchanged
--dry-run	Show what would change, but make no changes
--skip-restart	Validate and record the config without restarting
--no-auto-prep	Skip host-path re-verification before restart
--recursive-chown	For any configured mount whose host path is wrong-owned and populated, recursively chown it to uid 33 (www-data)

--box accepts a comma-separated list to apply across multiple boxes.

apt

Host-side apt packages (installed on the box host during apply).

lager box config apt add usbutils dfu-util --box my-lager-box
lager box config apt list [--json]
lager box config apt remove dfu-util

mount

Bind-mount a host path into the container.

lager box config mount add HOST_PATH CONTAINER_PATH [--readonly] --box my-lager-box
lager box config mount list [--json]
lager box config mount remove HOST_PATH CONTAINER_PATH [--yes]

mount add options:

Option	Description
--readonly	Mount as read-only
--no-auto-prep	Skip the auto mkdir/chown of the host path (use when the directory is provisioned externally)
--recursive-chown	If the host path already exists with the wrong owner and contains files, recursively chown it to uid 33 (www-data)

env

Container environment variables.

lager box config env set KEY=VALUE [KEY=VALUE ...] --box my-lager-box
lager box config env list [--json]
lager box config env unset KEY [KEY ...]

pip / cargo / npm

In-container language packages, installed when the container starts.

lager box config pip add requests rich --box my-lager-box
lager box config cargo add ripgrep --box my-lager-box
lager box config npm add left-pad --box my-lager-box
# each group also supports: list [--json], remove

pip add validates against PyPI by default; pass --no-validate-pypi to skip.

sysctl

Host sysctl values, persisted across reboots.

lager box config sysctl set net.ipv4.ip_forward=1 --box my-lager-box
lager box config sysctl list [--json]
lager box config sysctl unset net.ipv4.ip_forward

volume

Named docker volumes attached to the container (persist data across restarts).

lager box config volume add my-vol /opt/my-vol --box my-lager-box
lager box config volume list [--json]
lager box config volume remove my-vol [--yes]

Inspecting and editing

lager box config show --box my-lager-box        # full config
lager box config status --box my-lager-box      # one-line summary (clean / drift)
lager box config diff --box my-lager-box        # pending changes vs. last applied
lager box config validate --box my-lager-box    # check for errors
lager box config audit --box my-lager-box       # recent changes (supports --verb, --since, --tail)
lager box config edit --box my-lager-box        # open in $EDITOR, then apply

Backup, restore, and recovery

lager box config export ./box.json --box my-lager-box     # save current config to a file
lager box config import ./box.json --box my-lager-box      # replace config from a file
lager box config copy --from BOX_A --to BOX_B              # clone config between boxes
lager box config repair --box my-lager-box                 # restore the last applied config and restart

---

Notes

• Most editing commands only change the stored config — run apply to put changes into effect.
• udev rules, apt packages, and sysctl values are applied to the box host; mounts, env, and pip/cargo/npm apply inside the container.
• The config persists across container restarts and box updates. A user udev file (99-lager-user.rules) is preserved across lager update.
• --box accepts a name (from lager boxes) or an IP address.