Box Config

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:

Change the config — udev add, apt add, mount add, env set, etc. These only edit the stored config; nothing happens on the box yet.
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.

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Development

Utilities

Syntax

Global Options

How It Works

Commands

Command Reference

`udev`

`reset`

`restart`

`apply`

`apt`

`mount`

`env`

`pip` / `cargo` / `npm`

`sysctl`

`volume`

Inspecting and editing

Backup, restore, and recovery

Notes

​Syntax

​Global Options

​How It Works

​Commands

​Command Reference

​udev

​reset

​restart

​apply

​apt

​mount

​env

​pip / cargo / npm

​sysctl

​volume

​Inspecting and editing

​Backup, restore, and recovery

​Notes

Syntax

Global Options

How It Works

Commands

Command Reference

`udev`

`reset`

`restart`

`apply`

`apt`

`mount`

`env`

`pip` / `cargo` / `npm`

`sysctl`

`volume`

Inspecting and editing

Backup, restore, and recovery

Notes