Update

Update Lager Box software on Lager Boxes with comprehensive progress tracking and automatic configuration.

Syntax

lager update [OPTIONS]

Options

Option	Description
`--box BOX`	Lager Box name or IP address
`--version VERSION`	Release tag, semver pin, branch, or full 40-character commit SHA to update to (default: main). See Version pinning.
`--yes`	Skip confirmation prompt
`--check`	Dry run: report what will change without modifying the box
`--force`	Update even if the box reports it is already up to date, and force a clean rebuild (wipes the cached image and the cargo/npm volumes)
`--pull`	Pull the pre-built box image from GHCR for a release tag instead of building on the box (falls back to a local build on any miss)
`--no-pull`	Never pull a pre-built image; always build on the box
`--verbose` / `-v`	Show detailed output (default shows progress bar)

lager update targets one box per invocation. To update several, loop over them in your shell — the --all flag and its multi-box loop were removed in v0.18.2.

Pre-built box images

Release tags publish a box container image to the GitHub Container Registry. If a pull is enabled, the client does three things:

It resolves the tag to an immutable digest.
It pulls that digest, pinned to the box’s own architecture.
It verifies that the image reports the version you asked for.

Any miss at any step falls back to the local build, which is the original behavior. A miss can be a branch target rather than a release tag, an unpublished tag, an unreachable registry, or a mismatched image.

For lager update, pulling is off by default. It changes how the most load-bearing command in the fleet obtains the code it runs, so it soaks on Lager’s own boxes first. Pass --pull to opt a single run in, or set LAGER_BOX_IMAGE_PULL=1 to opt in a whole shell.This differs from lager install, which already uses a pre-built image for a release tag by default. --no-pull works the same way on both. It is the switch that routes a fleet around a bad published image, and it needs no CLI release.

Version pinning

Since lager 0.22.0, a semver value passed to --version resolves to the release tag vX.Y.Z. The leading v is optional (e.g. 0.26.0 or v0.26.0), and the common pre-release suffixes (-rc1, -beta2, -alpha, -preview) are accepted too. Release tags are the single source of truth for a pinned version.

# All three pin the same release tag (v0.26.0)
lager update --box my-lager-box --version v0.26.0 --yes
lager update --box my-lager-box --version 0.26.0 --yes
lager update --box my-lager-box --version v0.27.0-rc1 --yes

Since lager 0.41.0, a full 40-character commit SHA resolves to that exact commit:

lager update --box my-lager-box --version 5d84c68612384eed2854638c1e0941a4ff8b7893 --yes

Only the full 40 characters are accepted — a short hex prefix cannot be told apart from a branch name. Use this when you need a target that does not move. --version main is re-resolved against origin/main each time it runs, so it can mean a different commit minutes later. A commit has no pre-built image, because only release tags publish one. So a SHA builds on the box just as a branch does. The commit must also be reachable from a branch or tag on the remote. Any other value (main, staging, or a feature branch name) resolves to origin/<name> as before.

Per-release version branches (bare X.Y.Z branches) are deprecated in favour of tags. A value like 0.26.0 now resolves to the tag v0.26.0, not a branch of the same name. See RELEASE_PROCESS.md in the repository.

Usage

Basic Update

# Update to latest main branch
lager update --box my-lager-box --yes

# Update to staging branch
lager update --box my-lager-box --version staging --yes

# Update with verbose output
lager update --box my-lager-box --yes --verbose

# Force fresh Docker build (use for major code changes)
lager update --box my-lager-box --force --yes

Updating Several Boxes

There is no built-in multi-box update. Loop in your shell, and use --check first if you want to see which boxes are actually behind:

# Report what would change on each box, without modifying anything
for box in my-lager-box staging-box pi-box; do
  echo "== $box"
  lager update --box "$box" --check
done

# Then update them
for box in my-lager-box staging-box pi-box; do
  lager update --box "$box" --yes
done

A --all flag existed before v0.18.2 and was removed along with the multi-box loop it drove. A plain shell loop continues to the next box when one fails, so an unreachable box does not stop the run.

Update Process

The update command performs the following steps (shown in progress bar):

SSH Connection - Establish secure connection to Lager Box
Git Repository Check - Validate lager repository exists
Git Pull - Pull latest code from specified branch
Udev Rules - Install USB instrument access rules
Docker Build - Build updated containers (no-cache)
Firewall Setup - Configure UFW if needed
Customer Binaries - Set up custom binaries directory
J-Link Check - Verify debug probe software (optional)
Version Update - Record version in /etc/lager/version
Container Restart - Start updated containers
Status Verification - Confirm that the containers are up

Version Tracking

The Lager Box tracks its current version in /etc/lager/version. The lager boxes listing queries each configured box and shows its current version in the version column:

# List all boxes with their current versions
lager boxes

SSH Key Authentication

The update command automatically detects SSH key configuration:

With SSH keys: Updates proceed without password prompts
Without SSH keys: Prompts for password (interactive mode)

To set up SSH keys:

ssh-copy-id lagerdata@<box-ip>

Firewall Auto-Configuration

If UFW is not configured, the update command will:

Detect missing firewall rules
Offer to install and configure UFW
Apply secure defaults (VPN-only access to Lager ports)

# Manual firewall configuration
cli/deployment/security/secure_box_firewall.sh <box-ip>

Examples

# Standard update workflow
lager update --box my-lager-box --version main --yes

# Update several boxes
for box in my-lager-box staging-box; do lager update --box "$box" --yes; done

# Update several boxes to the staging branch
for box in my-lager-box staging-box; do lager update --box "$box" --version staging --yes; done

# Force fresh build on a specific box
lager update --box my-lager-box --force --yes

# Verbose update for troubleshooting
lager update --box my-lager-box --verbose

Troubleshooting

Update Fails at Git Pull

# Check the remote URL (should be HTTPS, not SSH)
ssh lagerdata@<box-ip> 'cd ~/box && git remote get-url origin'

# If it shows git@github.com:..., switch to HTTPS:
ssh lagerdata@<box-ip> 'cd ~/box && git remote set-url origin https://github.com/lagerdata/lager.git'

Container Build Fails

# SSH in and check Docker status
ssh lagerdata@<box-ip>
docker ps -a
docker logs controller

Firewall Issues

# Check firewall status
ssh lagerdata@<box-ip> 'sudo ufw status verbose'

# Re-run firewall setup
cli/deployment/security/secure_box_firewall.sh <box-ip>

Notes

Progress bar is disabled when --verbose is used
Container builds use --no-cache to ensure fresh builds
Version defaults to main if not specified
Update automatically verifies container health after restart
--check reports what will change without modifying the box, so it is the safe way to find out whether a box is behind
--force updates even when the box reports it is already current, wiping the cached image and the cargo/npm volumes (useful after major code changes)

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Development

Utilities

Syntax

Options

Pre-built box images

Version pinning

Usage

Basic Update

Updating Several Boxes

Update Process

Version Tracking

SSH Key Authentication

Firewall Auto-Configuration

Examples

Troubleshooting

Update Fails at Git Pull

Container Build Fails

Firewall Issues

Notes

​Syntax

​Options

​Pre-built box images

​Version pinning

​Usage

​Basic Update

​Updating Several Boxes

​Update Process

​Version Tracking

​SSH Key Authentication

​Firewall Auto-Configuration

​Examples

​Troubleshooting

​Update Fails at Git Pull

​Container Build Fails

​Firewall Issues

​Notes

Syntax

Options

Pre-built box images

Version pinning

Usage

Basic Update

Updating Several Boxes

Update Process

Version Tracking

SSH Key Authentication

Firewall Auto-Configuration

Examples

Troubleshooting

Update Fails at Git Pull

Container Build Fails

Firewall Issues

Notes