Skip to main content
A Lager Box is an ordinary Ubuntu machine running the Lager box software. This page takes a machine you already have — a mini PC on your bench, a rack server, or a virtual machine — and turns it into one.
If someone has already set up a box for you, you do not need this page. Go straight to Adding your First Lager Box.

​
What You Need

On the machine that will become the box:
  • An x86-64 processor. This is the only supported box architecture.
  • Ubuntu 22.04 or newer, including 24.04 LTS. See the note on Ubuntu 25.10 and later below.
  • A network connection, and an IP address or hostname you can reach.
  • An SSH server, and a login account with sudo whose password you know.
  • git installed. Everything else the box needs, including Docker, is installed for you — though see Step 1 for why installing Docker yourself is worth the extra minute.
On your computer:
  • Python 3.10 or higher and pip3.
  • An SSH client (ssh and ssh-keygen).
Run this on the machine to check all three at once before you start:
A first install builds the Lager container on the box itself and can take up to 30 minutes. Plan for the box to be busy for that long.
Ubuntu 25.10 and later, including 26.04 LTS, need one change before installing. Those releases default to sudo-rs, a reimplementation of sudo that does not accept the wildcard rules Lager writes to /etc/sudoers.d/. Installation stops early with wildcards are not allowed in command arguments and visudo: invalid sudoers file.Classic sudo is still installed on those releases. Switch to it on the box before you begin:
Keep a second session open with a working root shell while you do this, so you are not locked out if the switch does not take. Tracked in issue #313.
The box login account is root-equivalent by design. Provisioning a box requires root, so installation grants that account passwordless sudo for the commands Lager needs. Anyone who can log in as that account can obtain root on the box. Prefer a dedicated user on a dedicated machine, and treat its SSH key accordingly. The Install reference describes exactly which grants are written.

​
Step 1: Prepare the Machine

SSH into the machine and install git:
Confirm the account can use sudo. You will be asked for its password once during installation:
Optional, but it makes a failure easier to read: install Docker yourself now. The installer installs Docker if the machine does not have it, but it runs that step over SSH and reports package problems with less detail than apt gives you directly. Installing it by hand first means any problem surfaces with a real error message, in front of you:
Log out and back in afterward so the group membership takes effect, then check docker ps works without sudo.
The login account does not have to be named lagerdata. Whatever it is called, pass it as --user in Step 3, and record it with the box so later commands use the right account.
Note the machine’s IP address or hostname — you need it in Step 3:

​
Step 2: Install the Lager CLI

On your own computer, not on the box:
Check that it is available:

​
Step 3: Run the Installer

lager install does the rest: it configures SSH keys and sudo, deploys the box code, installs Docker if the machine does not have it, builds and starts the Lager container, and configures the firewall.
The command checks SSH connectivity, prints a summary of what it is about to do, and asks you to confirm before it changes anything. The first time, SSH will not be authorized yet. Lager notices, and offers to fix it:
Accept it and enter the box account’s password once. Lager installs a dedicated key at ~/.ssh/lager_box, and every later step — and every later command — runs without a password. If you decline, the install stops and tells you to run lager ssh-setup --box <name-or-ip>, which does the same thing on its own. Deployment then runs, streaming its output. Leave it alone until it finishes. If it fails partway, fix what it reports and run the same command again. lager install is safe to re-run: it rewrites its own configuration each time and skips work that is already done, so a second run picks up rather than starting over.
To install a specific release instead of the latest code, add --version — for example --version v0.39.0. See the Install reference for every option.

​
Step 4: Networking and the Firewall

Installation configures a UFW firewall on the box that restricts the Lager service ports to your VPN, the Docker bridge, and localhost. SSH on port 22 is always left open, so this cannot lock you out of the machine. How you point it at your network depends on what you use: Tailscale. Nothing to do. If Tailscale is running on the box, the installer detects the tailscale0 interface and allows the Lager ports on it. A corporate VPN. Name the interface explicitly. Find it on the box:
Then pass it to the installer — cscotun0 for Cisco Secure Client, tun0 for OpenConnect, and so on:
The interface must exist on the box at the moment you run the installer. If the VPN is not connected, the firewall step fails with Corporate VPN interface <name> not found and lists the interfaces it did find. Connect the VPN and run the install again.
Neither. Add --skip-firewall to leave UFW alone entirely, and secure the machine by whatever means you already use.

​
Step 5: Name the Box and Verify

When deployment finishes, the installer offers to add the box to your local configuration:
The name is yours to choose and is local to your computer. If you skipped that prompt, add it by hand — --user is required:
Check that the box answers:
Expected output:
Then see what hardware it can find:
An empty list is the correct answer if you have not connected any instruments yet.

​
Running a Lager Box in a Virtual Machine

A VM works as a Lager Box, provided the guest is x86-64 and runs Ubuntu 22.04 or newer. Everything above applies unchanged. The one thing that differs is hardware access. Instruments and debug probes are USB devices, and the Lager container reaches them through the host’s /dev. A USB device the guest cannot see is a device Lager cannot use. So if the box will drive real hardware, configure USB passthrough in your hypervisor before you connect anything. Prefer passing through an entire USB controller rather than individual devices. Debug probes re-enumerate when they reset, and Lager power-cycles USB hub ports as a normal part of testing — both of which change or drop a device identity that per-device passthrough is pinned to. A whole controller keeps working across those events. A VM with no hardware attached is still useful for trying Lager out, and needs no passthrough at all.

​
Troubleshooting

Installation stops before deploying anything. Install git on the box and run the command again:
Expected on a first install — answer yes to the prompt that follows and enter the box account’s password once. To do it as a separate step instead:
If the password is rejected, confirm you are using the box account’s own password, and that the box allows password authentication for that account.
The interface named by --corporate-vpn did not exist on the box when the firewall step ran. The error lists the interfaces that do exist. Connect the VPN, confirm the name with ip -br link on the box, and run the install again.
A first install builds the container image on the box, which is the longest step by far and can run for many minutes with little output. Let it run. The command gives up on its own after 30 minutes.
The box is running sudo-rs, the default sudo on Ubuntu 25.10 and later. Installation stops at the passwordless-sudo step with visudo: invalid sudoers file before anything is deployed.Switch the box to classic sudo and run the install again:
See the warning near the top of this page for the full explanation.
Installation prints the manual commands to run on the box. Run them one at a time rather than as a block, so you can see which one actually fails — the installer reports this whole sequence as a single error:
If restart is the step that fails, Docker itself is not starting and installing it again will not help. Ask it why:
Once Docker runs, log out and back in so the group membership takes effect, then run lager install again. It detects the working Docker and skips this step.
x86-64 is the only supported box architecture. Check with uname -m on the machine — it must report x86_64. Other architectures are not supported, and an install may appear to succeed while hardware support is missing.
For problems that appear after the box is up and running, see Troubleshooting.

​
Next Steps

Your box is running. Now connect to it and give it something to do: