Install

Install Lager box code onto a box

Deploy the Lager box software, Docker container, and supporting tools onto a new or existing box.

Syntax

lager install [OPTIONS]

Options

Option	Type	Default	Description
--box TEXT	string		Box name (uses stored IP and username from .lager config)
--ip TEXT	string		Target box IP address or DNS hostname
--user TEXT	string	lagerdata	SSH username
--version TEXT	string	main	Box version to deploy: a release tag (e.g. v0.15.0) or a git branch
--skip-jlink	flag		Skip J-Link installation (pyOCD is always installed)
--skip-firewall	flag		Skip UFW firewall configuration
--skip-verify	flag		Skip post-deployment verification
--corporate-vpn TEXT	string		Corporate VPN interface name for firewall rules (e.g., tun0)
--yes	flag		Skip confirmation prompts
--pull	flag	on	Use the pre-built box image when the target is a release tag (the default)
--no-pull	flag		Always build the box image on the box
--help			Show help message and exit

Either --box or --ip is required. If both are provided, the command exits with an error.

The Box Image

The slowest part of an install is obtaining the box’s Docker image. Building it on the box takes roughly 14 minutes — an install always pays the full cost, because the deployment prunes the builder cache before it starts, so there is never a warm layer cache to reuse.

Every release tag publishes a pre-built image, and lager install uses it by default: about 2 minutes instead of 14.

This only applies when --version names a release tag. Branches such as main and staging have no published image and always build on the box, so pinning a release tag is the difference between a two-minute install and a fourteen-minute one.

The image is verified before it is used. It is fetched by immutable digest rather than by tag, and it must carry a label naming the exact version that was requested; an image that is unlabelled or claims a different version is discarded. If anything at all goes wrong — the tag has no published image, the box cannot reach the registry, the image fails verification — the install falls back to building on the box, exactly as it always did. A slow install that works beats a fast one that does not.

Pass --no-pull to skip the pre-built image and always build. Setting LAGER_BOX_IMAGE_PULL=0 in the environment does the same for every command in that shell.

What Gets Installed

Component	Description
Docker container	Lager service container (ports 5000 and 8765) with auto-restart
pyOCD	Open-source debug probe tool (automatic)
J-Link	SEGGER debug probe software (optional, skipped with --skip-jlink)
UFW firewall	Restricts service ports to VPN and localhost (skipped with --skip-firewall)
Box code	Python libraries and services in ~/box

Installation Flow

1. Resolve target - Looks up box IP from --box name or uses --ip directly
2. Verify SSH - Tests key-based authentication and settles which identity the rest of the command offers
3. Show summary - Displays what will be installed and asks for confirmation
4. Deploy - Runs the deployment script. About 2 minutes when the pre-built image is used, or up to 30 minutes when the box builds it (see below)
5. Store version - Writes the CLI version to /etc/lager/version on the box
6. Add to config - Optionally adds the box to your local .lager config

Examples

# Install to a new box by IP
lager install --ip 192.168.1.100

# Install to a stored box
lager install --box my-lager-box

# Install a specific release tag
lager install --ip 192.168.1.100 --version v0.15.0

# Install a specific branch with a custom user
lager install --ip 192.168.1.100 --user pi --version staging

# Install with corporate VPN firewall support
lager install --ip 192.168.1.100 --corporate-vpn tun0

# Skip optional components
lager install --ip 192.168.1.100 --skip-jlink --skip-firewall

# Force a local build of the box image instead of using the published one
lager install --box my-lager-box --version v0.39.1 --no-pull

# Non-interactive installation
lager install --ip 192.168.1.100 --yes

Passwordless sudo

Installation configures passwordless sudo for the box login user. The CLI drives the box over non-interactive SSH, where sudo has no terminal to prompt against, so the grants have to be in place before provisioning can run.

Lager writes these files, and only these files, under /etc/sudoers.d/:

File	Written by	Grants
lagerdata-udev	lager install	udev rule deployment, modprobe blacklist, Docker group and service control, firewall helper install/run, /etc/lager file writes
lager-box-config	lager install, lager update	apt-get, sysctl, and the path-scoped writes lager box-config apply needs
lager-bench-json	Operator, on boxes predating the grant in lagerdata-udev	Writing /etc/lager/bench.json

The box login user is root-equivalent by design. Provisioning a box requires root — deploying udev rules runs commands as root by construction, and apt-get executes arbitrary commands as root through its own configuration. The grants above are written as specific commands to keep the blast radius small and the file readable, but they are not a privilege boundary: anyone who can log in as the box user can obtain root on that box.

Treat the box login account as equivalent to root when deciding who holds its SSH key, and prefer a dedicated user on a dedicated machine.

Each of the three files is regenerated in full on every run — that is what keeps a box on the current grant shape. A grant added inside one of them is lost the next time it is written, so each file opens with a header saying so.

Lager never reads, edits, or removes any other file in /etc/sudoers.d/. If you or a box-management platform need additional grants, put them in a separate file there — for example /etc/sudoers.d/zz-local, which sorts after Lager’s files so its rules win — and Lager will leave it alone, including during lager uninstall.

SSH Authentication

Install requires key-based SSH authentication. It offers ~/.ssh/lager_box — the key lager ssh-setup and lager install generate — explicitly, because that is not a filename ssh tries on its own. If the box does not accept it, install falls back to your own default identities, so a box you authorized with ssh-copy-id works unchanged.

If neither authenticates, install offers to set the key up for you:

No SSH key on this machine is authorized on the box.

Set up the lager_box key now? (one box-password prompt, then the rest of the
install runs unattended) [Y/n]:

Accepting prompts for the box password once, installs the key, and every later step of the install runs unattended. --yes accepts it without asking. Declining stops the install and points you at lager ssh-setup --box <name-or-ip>, which does the same thing as a separate step.

Install does not offer a password fallback for the deployment itself: a box configured with PasswordAuthentication no never receives the password, so the resulting “password failed” message described something that had not happened.

For new hosts, the SSH host key is accepted automatically. If the host key has changed since a previous connection, the command asks you to verify the change manually before proceeding.

Install does not write to ~/.ssh/config. Earlier versions added a per-IP Host block naming the key; that block was deleted whenever the file was regenerated by another tool, and it disabled host-key verification for the box. The identity is passed per command instead.

Notes

• For a step-by-step walkthrough, see Setting Up a Lager Box
• Requires SSH client tools (ssh, ssh-keygen) to be installed locally
• The deployment script is bundled with the lager-cli package
• After installation, verify connectivity with lager hello --box <name>
• Use lager update to deploy code updates to an already-installed box
• Use lager uninstall to remove Lager software from a box