Boxes

Manage Lager Box names, IP addresses, and configurations for local development.

Syntax

lager boxes COMMAND [OPTIONS]

Commands

Command	Description
`add`	Add a new box configuration
`add-all`	Add all boxes from Tailscale network
`delete`	Delete a box configuration
`edit`	Edit an existing box configuration
`list`	List all configured boxes
`delete-all`	Delete all box configurations
`export`	Export box configuration to JSON
`import`	Import box configuration from JSON
`lock`	Lock a box to prevent others from using it
`unlock`	Unlock a box

Command Reference

`add`

Add a new Lager Box configuration.

lager boxes add --name NAME --ip IP --user USER [OPTIONS]

Options:

--name (required) - Name to assign to the box
--ip (required) - IP address or hostname of the box
--user (required) - SSH username for the box (the account you log in as)
--version - Lager Box version/branch (e.g., staging, main)
--yes - Confirm without prompting

--user is required. It previously defaulted to lagerdata, but since most boxes use a different login account, the default was removed so the correct user is always recorded for SSH, updates, and lager ssh.

Examples:

# Add a basic box
lager boxes add --name my-lager-box --ip <BOX_IP> --user lager

# Add with a Raspberry Pi default account
lager boxes add --name pi-lager-box --ip <BOX_IP> --user pi

# Add with version tracking
lager boxes add --name staging-lager-box --ip <BOX_IP> --user lager --version staging

`add-all`

Automatically add all Lager Boxes found on your Tailscale network.

lager boxes add-all [--yes]

Options:

--yes - Confirm without prompting

This command scans your Tailscale network for devices with names 5-8 characters long, the typical Lager Box naming convention. It adds each one as a box with an uppercase name. How it works:

Runs tailscale status to discover devices
Filters for devices with names 5-8 characters long
Converts names to uppercase
Skips a box that already exists with the same name and IP. A box whose IP changed is updated without a prompt
Adds new boxes to your configuration

Example:

# Scan and add all boxes
lager boxes add-all

# Output:
Scanning Tailscale network for lager boxes...

Found 3 lager box(es):

  LABGW1 → <BOX_IP>
  TESTGW → <BOX_IP>
  DEVBOX → <BOX_IP>

Add all 3 box(es)? [Y/n]: y

  LABGW1: added
  TESTGW: added
  DEVBOX: already exists (skipped)

Summary:
  Added:   2
  Skipped: 1

[OK] Successfully added 2 box(es)

# Add without confirmation prompt
lager boxes add-all --yes

`delete`

Delete a box configuration.

lager boxes delete --name NAME [--yes]

Examples:

# Delete with confirmation prompt
lager boxes delete --name old-lager-box

# Delete without confirmation
lager boxes delete --name old-lager-box --yes

`edit`

Edit an existing box configuration.

lager boxes edit --name NAME [OPTIONS]

Options:

--name (required) - Name of the box to edit
--ip - New IP address
--user - New SSH username
--version - New Lager Box version/branch
--new-name - Rename the box
--yes - Confirm without prompting

Examples:

# Change IP address
lager boxes edit --name my-lager-box --ip <BOX_IP>

# Rename a box
lager boxes edit --name old-name --new-name new-name

# Update SSH user and version
lager boxes edit --name pi-lager-box --user pi --version staging

`list`

List all configured boxes with live version status. This is also the default behavior when running lager boxes with no subcommand.

lager boxes list
lager boxes          # same as list

The command queries each box API on port 9000 (/lock and /status) to display real-time version, status and lock information. All boxes are queried at the same time. A box that is powered down or mid-update now costs only its own timeout. It no longer delays the others. On a terminal the table is printed straight away, with every row reading pending. A spinner turns beside each unanswered status and locked by cell. Each row fills in as its box answers. A countdown shows how long the outstanding boxes have left:

name        ip             user      version   status      locked by
====================================================================
box-one     <BOX_IP>       charles   0.47.0    current
box-two     <BOX_IP>       charles   -         ⠹ pending   ⠹
Waiting on 1 box - 5s left, Ctrl+C to stop waiting

The live table always shows locked by, because no lock is known until a box answers. A column that arrives later shifts every row below it. Press Ctrl+C to stop waiting without losing the boxes that did answer: the rest are marked cancelled and the table prints immediately. A box that never answers is given up on shortly after the countdown reaches zero and marked no response, so the command always terminates. Piped into a file or a CI log, the command uses none of the live display. It prints the final table once, exactly as shown above. Output:

name           ip            user        version        status         locked by
=================================================================================
my-lager-box   <BOX_IP>      lagerdata   0.47.0         current
staging-box    <BOX_IP>      lagerdata   0.46.2         needs update   alice
pi-box         <BOX_IP>      pi          0.47.0 (main)  current
offline-box    <BOX_IP>      lagerdata   -              unreachable

Your CLI: 0.47.0
1 box needs updating
1 box did not report a version

In this final table the locked by column appears only when a box is locked. A version from a branch or a commit shows the ref in brackets, for example 0.47.0 (main). A box on a release tag shows only the version. lager hello prints the full ref with the commit. Status Colors:

Status	Color	Meaning
`current`	Green	Box version matches CLI version
`needs update`	Yellow	Box version is older than CLI
`newer`	Cyan	Box version is newer than CLI
`unreachable`	Red	Box could not be contacted
`timeout`	Red	Connection timed out
`old box`	Red	Box does not support version reporting
`no IP`	Red	The stored entry has no IP address
`bad response`, `invalid JSON`, `HTTP <code>`, `error`	Red	The box answered, but not with a usable version
`sign-in required`, `session rejected`	Red	The box is access-gated. The CLI prints the `lager login` command to run
`no access`, `auth server down`, `token rejected`	Red	The box is access-gated and the gateway refused. An access grant or an admin is needed, not a sign-in
`pending`	Grey	Shown on a terminal only, with a spinner, while that box has yet to answer
`no response`	Red	The box never answered, and was given up on after the countdown
`cancelled`	Red	The box had not answered when `Ctrl+C` stopped the wait

If a box shows root in the locked by column, the command prints a warning. Such a lock usually comes from inside a Docker container. Use lager boxes lock --user to name the user next time.

`delete-all`

Delete all box configurations.

lager boxes delete-all [--yes]

`export`

Export box configuration to JSON file. The export is the whole .lager file, so it also carries your defaults and cached nets, not only the boxes.

lager boxes export [--output FILE]

Options:

--output / -o - Output file path (prints to stdout if not specified)

Examples:

# Export to file
lager boxes export --output boxes.json

# Export to stdout
lager boxes export

`import`

Import box configuration from JSON file.

lager boxes import FILE [--merge] [--yes]

Options:

FILE - Path to JSON file to import
--merge - Merge with existing boxes (default: replace)
--yes - Confirm without prompting

Examples:

# Replace all boxes with imported config
lager boxes import boxes.json --yes

# Merge imported boxes with existing
lager boxes import new-boxes.json --merge --yes

`lock`

Lock a box to prevent other users from using it. See Box Locking for full details.

lager boxes lock --box NAME [--user USER]

Options:

--box (required) - Name of the box to lock
--user - Username to lock as. Use it inside a Docker container, where the user is otherwise root

Example:

lager boxes lock --box my-lager-box

`unlock`

Unlock a box to allow other users to use it. See Box Locking for full details.

lager boxes unlock --box NAME [--user USER] [--force]

Options:

--box (required) - Name of the box to unlock
--user - Holder to unlock as, for a lock recorded under a name other than your user name
--force - Force unlock even if locked by another user

Without --force, unlock releases a lock that the CLI counts as yours, such as the automatic lock of your own CI job. Examples:

# Unlock your own lock
lager boxes unlock --box my-lager-box

# Force unlock another user's lock
lager boxes unlock --box my-lager-box --force

Configuration Storage

The boxes commands write box configurations to ~/.lager in your home directory. If LAGER_CONFIG_FILE_DIR is set, they write .lager in that directory instead. The boxes are under the BOXES key:

{
  "BOXES": {
    "my-lager-box": {
      "ip": "<BOX_IP>",
      "user": "lagerdata",
      "version": "main"
    },
    "pi-box": "<BOX_IP>"
  }
}

Entries can be:

Simple: Just an IP address string
Full: Object with ip, user, and version fields

To read boxes, the CLI merges the global file with the .lager files that it finds in your project directories. The file closest to the current directory wins.

Validation

The boxes commands perform validation:

Duplicate detection: add warns about a box with the same name or IP and asks before it continues. If you confirm, the entry is overwritten, and another box with the same IP is deleted
Address validation: Validates the IP address or hostname format
Confirmation: Shows before/after state for edit operations

Examples

# Set up a new bench
lager boxes add --name my-lager-box --ip <BOX_IP> --user lager
lager boxes add --name staging-box --ip <BOX_IP> --user lager
lager boxes add --name pi-box --ip <BOX_IP> --user lager

# Export configuration for team sharing
lager boxes export -o bench-config.json

# Import on another machine
lager boxes import bench-config.json --yes

# Clean up
lager boxes delete-all --yes

Notes

Box names must be unique
add keeps IP addresses unique: a confirmed add replaces the box that had the same IP
--user is required for lager boxes add. add-all stores entries without a user, and commands then use lagerdata
Use --merge when importing to preserve existing boxes
lager boxes list needs each box to answer on port 9000 to show its version and lock state

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Security

Development

Utilities

Syntax

Commands

Command Reference

`add`

`add-all`

`delete`

`edit`

`list`

`delete-all`

`export`

`import`

`lock`

`unlock`

Configuration Storage

Validation

Examples

Notes

​Syntax

​Commands

​Command Reference

​add

​add-all

​delete

​edit

​list

​delete-all

​export

​import

​lock

​unlock

​Configuration Storage

​Validation

​Examples

​Notes

Syntax

Commands

Command Reference

`add`

`add-all`

`delete`

`edit`

`list`

`delete-all`

`export`

`import`

`lock`

`unlock`

Configuration Storage

Validation

Examples

Notes