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. To opt in a whole shell, set LAGER_BOX_IMAGE_PULL to 1, true or yes (in any letter case). Any other value leaves the pull off.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.

More rules for the update pull:

--force never pulls. It always builds the image on the box.
--pull together with --no-pull is a usage error.
The pull runs before the update stops the container, so the box keeps serving during the download. A miss leaves the box on its previous version.
The update records the image source in /etc/lager/image-source: ghcr:<digest> for a pulled image, or local:<build-hash> for a build.

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.

Check Mode

--check changes nothing on the box. It prints a preview:

Update preview
  Box:        my-lager-box (100.64.1.42)
  Current:    0.46.2
  Target:     main
  Code:       ...
  Deps:       ...
  Container:  ...
  Host CLI:   will upgrade (0.46.2 -> 0.47.0)
  Estimated:  ...

Current: comes from /etc/lager/version. The preview does not show the deployed ref. Use lager hello for the ref.

Exit code	Meaning
`0`	The box is in sync. Nothing to do
`1`	The update changes something, or the check failed
`2`	No SSH key is confirmed for the box, or git could not compare the box with the target

Exit 1 does not always mean that the box is behind. The check also exits 1 when it fails. Examples are an SSH timeout, a failed probe of the box state, and a box directory that is not a git checkout. A failed git fetch also gives 1, and that includes a commit SHA that the box cannot fetch. A box locked by another holder also gives 1. Read the output before you treat 1 as “update needed”.

Update Process

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

SSH Check - Confirm key-based SSH access to the Lager Box
Inspect and Fetch - Read the box state, then fetch the target version
Pull Updates - Check out the target version on the box
Host Setup - Check the udev rules, the modprobe blacklists, the sudoers files and the host CLI
Image Pull - With --pull and a release tag, pull the pre-built image
Container Stop and Build - Stop the running container, then build the image on the box if the update did not pull one
Directories - Set up the directories that the container mounts, such as the custom binaries directory
Version Update - Record the version in /etc/lager/version and the deployed ref in /etc/lager/ref
Container Start - Start the new container
Status Verification - Wait for the services, then confirm that they answer
J-Link - Install J-Link if the box does not have it (a failure here is not fatal)
Host CLI - Reinstall the lager CLI in ~/.lager_venv on the box host, because the code changed

A host CLI failure is not fatal. The update prints a warning, and the final summary adds Host CLI on the box host was NOT updated: .... The box host needs python3 3.10 or newer, or the update skips this step with a warning. A box that is already up to date still gets the host CLI if its copy is absent, broken or older. lager update does not change the host firewall.

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

The box also records the deployed ref in /etc/lager/ref, as <ref>@<short-sha> (for example main@85c1b64). If the update cannot read the commit, the file holds the bare <ref>. lager update writes the file on every successful run, including a run where the box is already up to date. lager install writes it too. The version number alone cannot tell a branch deploy from a release deploy, so two commands show the ref:

lager hello shows the full ref. A ref that is not a release tag adds -- not a release build.
lager boxes shows <version> (<ref-name>) for a ref that is not a release tag.

A box last deployed by a CLI older than 0.43.0 has no ref file.

SSH Key Authentication

The update command checks for a working SSH key before it changes anything:

With a working key: The update runs without password prompts.
Without a working key: The update offers to set up the lager_box key. That setup asks for the box password once.
If the key setup fails: The update asks whether to continue with password authentication.
With --yes: The update accepts both prompts.
With --check: The update does not set up a key. It exits 2 when no key works.

To set up the key as a separate step:

lager ssh-setup --box my-lager-box

Firewall

lager update does not install, change or run the host firewall. lager install configures it. To run the firewall script again, run it on the box:

ssh -t <user>@<box-ip> 'sudo /usr/local/lib/lager/secure_box_firewall.sh'

The script resets ufw before it writes its rules, so it removes rules that you added by hand. On the default lagernet network, these rules do not filter the ports that the container publishes. See lager install and the Security Model section of SECURITY.md.

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 lager

Firewall Issues

# Check firewall status (sudo can prompt, so allocate a terminal)
ssh -t lagerdata@<box-ip> 'sudo ufw status verbose'

# Re-run firewall setup on the box
ssh -t lagerdata@<box-ip> 'sudo /usr/local/lib/lager/secure_box_firewall.sh'

Notes

Progress bar is disabled when --verbose is used
Container builds use the BuildKit layer cache. --force removes the cached image and the cargo/npm volumes first
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

Check Mode

Update Process

Version Tracking

SSH Key Authentication

Firewall

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

​Check Mode

​Update Process

​Version Tracking

​SSH Key Authentication

​Firewall

​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

Check Mode

Update Process

Version Tracking

SSH Key Authentication

Firewall

Examples

Troubleshooting

Update Fails at Git Pull

Container Build Fails

Firewall Issues

Notes