Python

Run Python scripts inside the container on the specified box for test automation, hardware control, and data processing.

Syntax

lager python [OPTIONS] [RUNNABLE] [ARGS]...

Global Options

Option	Short	Type	Default	Description
`--box TEXT`		String		Lager Box name or IP address
`--env FOO=BAR`		Multiple		Set environment variables for the script
`--passenv VAR`		Multiple		Pass environment variables from current shell
`--kill TEXT`		String		Kill a specific running process by its process ID
`--kill-all`		Flag		Kill all running scripts
`--signal SIGNAL`		Choice	`SIGTERM`	Signal to use with `--kill`/`--kill-all`
`--download FILE`		Multiple		Download files from box after script completes
`--allow-overwrite`		Flag		Allow overwriting existing local files with `--download`
`--timeout SECONDS`		Integer	0 (none)	Maximum runtime in seconds. The box caps an attached run at 300; with `--detach` no cap applies
`--detach`	`-d`	Flag		Run in detached mode (background)
`--port PORT`	`-p`	Multiple		Forward ports to the Python process
`--add-file FILE`		Multiple		Add extra files to upload with script
`--reattach TEXT`		String		Reattach to a detached process by its process ID
`--continue TEXT`		String		Resume a script paused at a breakpoint, by its process ID
`--console TEXT`		String		Connect to the interactive console of a paused script, by its process ID
`--help`		Flag		Show help message and exit

Arguments:

RUNNABLE - Python script file or directory to execute (required unless a process-management flag such as --kill, --kill-all, --reattach, --continue, or --console is used)
ARGS - Additional arguments passed to the script

Signal choices for --kill/--kill-all: SIGINT, SIGQUIT, SIGABRT, SIGKILL, SIGUSR1, SIGUSR2, SIGTERM, SIGSTOP

Basic Usage

# Run a Python script on the box
lager python script.py --box my-lager-box

# Run with arguments
lager python test.py --box my-lager-box -- --verbose --target DUT1

# Run a directory as a module
lager python my_test_suite/ --box my-lager-box

Environment Variables

Setting Variables

# Set explicit environment variables
lager python test.py --box my-lager-box --env API_KEY=abc123 --env DEBUG=true

# Pass variables from your current shell
export SECRET_TOKEN=xyz
lager python test.py --box my-lager-box --passenv SECRET_TOKEN

Auto-Injected Variables

The following environment variables are automatically available inside your script:

Variable	Description
`LAGER_OUTPUT_CHANNEL`	File path for structured output (see Structured Output below)
`LAGER_PROCESS_ID`	Unique UUID for this execution
`LAGER_RUNNABLE`	Path to the script being executed
`LAGER_BOX`	Box name (if `--box` was provided)

File Downloads

Download files generated by your script after it completes:

# Download a single file
lager python data_processor.py --box my-lager-box --download results.csv

# Download multiple files
lager python test.py --box my-lager-box --download report.json --download log.txt

# Allow overwriting existing local files
lager python test.py --box my-lager-box --download results.csv --allow-overwrite

Files are downloaded to the current working directory using the basename of the remote path. If a local file with the same name already exists, the command fails unless --allow-overwrite is set. Gzip-compressed files are automatically decompressed during download.

Detached Mode

Run scripts in the background without waiting for output:

# Start a long-running script in the background
lager python long_running.py --box my-lager-box --detach

In detached mode:

The command returns as soon as the box accepts the job. It returns before the script starts, and before any setup that the script needs (unpacking a module directory, installing its requirements.txt)
No stdout/stderr is streamed back
The script continues running on the box
Use --reattach to see its output, --kill to stop it later

The launch returns before the setup runs. A job can therefore fail to start after the prompt comes back — a requirements.txt that will not install, say. You see that failure through the job, not at the prompt. --reattach shows the failure and exits non-zero:

lager python ./my_module --box my-lager-box --detach
# Process detached (Process ID: 7f3c...)

lager python --reattach 7f3c... --box my-lager-box
# ERROR: Could not find a version that satisfies the requirement ...
# Process exited with code 1

A detached run takes the box lock. A box on 0.42.0 or later then holds that lock while the job runs, and releases it when the job ends. The CLI prints Box 'my-lager-box' is held for the detached run and released when it ends. An older box keeps the lock after the job ends. The CLI then prints release with: lager boxes unlock --box my-lager-box. See locking.

Killing Running Scripts

--kill takes the process ID that the detached launch printed.

# Kill with default SIGTERM
lager python --kill <PROCESS_ID> --box my-lager-box
# Process <PROCESS_ID> killed

# Kill with specific signal
lager python --kill <PROCESS_ID> --signal SIGKILL --box my-lager-box

# Kill every running script
lager python --kill-all --box my-lager-box
# All processes killed

Port Forwarding

Forward network ports from the box to your local machine:

# Forward port 8080
lager python web_server.py --box my-lager-box -p 8080

# Forward with different local/remote ports
lager python server.py --box my-lager-box -p 8080:80

# Forward with protocol
lager python server.py --box my-lager-box -p 8080:80/tcp

Port format: SRC_PORT[:DST_PORT][/PROTOCOL]

Timeout

Limit script execution time:

# Kill after 5 minutes
lager python analysis.py --box my-lager-box --timeout 300

0, the default, means no limit.
An attached run is capped at 300 seconds. A larger value runs for 300 seconds, and the box writes the cap to its log.
A detached run has no cap. The box applies the value only when you give one.

When a script exceeds the timeout, the box sends the signals:

First, SIGTERM is sent. The CLI prints Script terminated due to timeout. and exits with code 124
If the script does not exit within 5 seconds, SIGKILL is sent. The CLI prints Script forcibly killed due to timeout. and exits with code 137

Structured Output

Scripts running on the box can send structured data back to the CLI using the lager.core.output() function. This uses a dedicated output channel (file descriptor 3) separate from stdout/stderr.

Box-Side API

from lager.core import output, OutputEncoders

# Output a Python dict (default: pickle encoding)
output({'status': 'pass', 'measurement': 3.14})

# Output as JSON
output({'voltage': 3.3, 'current': 0.5}, encoder=OutputEncoders.JSON)

# Output as YAML
output({'device': 'PSU-1', 'readings': [1.0, 2.0]}, encoder=OutputEncoders.YAML)

# Output raw binary data
output(image_bytes, encoder=OutputEncoders.Raw)

Available encoders:

Encoder	ID	Use Case
`OutputEncoders.Raw`	1	Binary data (images, files)
`OutputEncoders.Pickle`	2	Python objects (default)
`OutputEncoders.JSON`	3	JSON-serializable data
`OutputEncoders.YAML`	4	YAML-serializable data

Structured output is printed to the CLI console as it arrives. Standard stdout and stderr are streamed separately in real time.

Module Includes

If your script depends on local modules, configure includes in a .lager file in your project. The file is JSON:

{
  "includes": {
    "my_lib": "../my_lib",
    "fixtures": "/path/to/fixtures"
  }
}

A relative path is relative to the .lager file. The CLI starts at the directory of the script, and searches up the directory tree for a .lager file. It then zips the script along with all include directories before uploading to the box.

# Script can import from included directories
lager python test.py --box my-lager-box

In test.py:

from my_lib import helpers
from fixtures import test_data

Additional Files

Upload extra files alongside your script:

lager python flash_and_test.py --box my-lager-box --add-file firmware.hex --add-file config.json

Files are available in the same directory as your script on the box.

Exit Codes

Exit Code	Meaning
0	Success
255	The CLI did not get the exit code from the box. It prints `Failed to retrieve script exit code.`
124	Script terminated by SIGTERM (timeout)
137	Script killed by SIGKILL (timeout, force)
128+N	Script stopped by signal N
Other	Script’s own exit code

Box Lock

lager python takes the box lock when it runs a script. Another user then cannot drive the same box at the same time. See locking.

An attached run holds the lock while the script runs. The command releases it when it exits.
If another user holds the lock, the command fails at once on your computer. In CI, it waits for the lock.
--kill, --kill-all, --reattach, --continue, and --console do not take the lock.
Set LAGER_AUTO_LOCK_DISABLE=1 to run without the lock.

Examples

# Basic script execution
lager python script.py --box my-lager-box

# Run with environment variables
lager python test.py --box my-lager-box --env API_KEY=abc123 --env DEBUG=true

# Run in detached mode
lager python long_running.py --box my-lager-box --detach

# Download files after completion
lager python data_processor.py --box my-lager-box --download results.csv

# Kill running script
lager python --kill <PROCESS_ID> --box my-lager-box

# Run with port forwarding
lager python web_server.py --box my-lager-box -p 8080

# Run with timeout
lager python analysis.py --box my-lager-box --timeout 300

# Upload extra files with script
lager python flash_test.py --box my-lager-box --add-file firmware.hex

# Pass arguments to the script
lager python test.py --box my-lager-box -- --device DUT1 --verbose

Hardware Test Script Example

# test_power.py - run with: lager python test_power.py --box my-lager-box
from lager import Net, NetType
from lager.core import output, OutputEncoders
import time

# Get the power supply net
psu = Net.get("PSU_CH1", type=NetType.PowerSupply)

# Set voltage and enable
psu.voltage(value=3.3, ovp=3.6)
psu.enable()
time.sleep(1)

# Read state
state = psu.get_full_state()
print(f"Voltage: {state['voltage']}V, Current: {state['current']}A")

# Send structured results
output({
    'test': 'power_on',
    'voltage': state['voltage'],
    'current': state['current'],
    'status': 'pass' if state['voltage'] > 3.0 else 'fail'
}, encoder=OutputEncoders.JSON)

# Cleanup
psu.disable()

Notes

Use --env for script-specific configuration values
Use --passenv for secrets/tokens from your current shell
--download retrieves files only after script completion (not during)
Port forwarding syntax: SRC_PORT[:DST_PORT][/PROTOCOL]
Output is streamed in real time via a multiplexed HTTP protocol with keepalive (20-second interval)

Installing Python packages

Scripts run inside the Lager Python container on the box. To install the packages that your scripts depend on, use the declarative lager box-config pip commands. Those commands record the packages in the box config and rebuild the container. The packages then persist across lager python runs and box updates.

# Add one or more packages
lager box-config pip add pandas requests --box my-box

# List configured packages
lager box-config pip list --box my-box

# Remove a package
lager box-config pip remove numpy --box my-box

# Apply the changes (rebuild the container)
lager box-config apply --box my-box

See the Box Config reference for the full declarative provisioning workflow (pip/cargo/npm packages, apt, udev, mounts, env, and more).

The standalone lager pip command was removed and folded into lager box-config pip.

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Development

Utilities

Syntax

Global Options

Basic Usage

Environment Variables

Setting Variables

Auto-Injected Variables

File Downloads

Detached Mode

Killing Running Scripts

Port Forwarding

Timeout

Structured Output

Box-Side API

Module Includes

Additional Files

Exit Codes

Box Lock

Examples

Hardware Test Script Example

Notes

Installing Python packages

​Syntax

​Global Options

​Basic Usage

​Environment Variables

​Setting Variables

​Auto-Injected Variables

​File Downloads

​Detached Mode

​Killing Running Scripts

​Port Forwarding

​Timeout

​Structured Output

​Box-Side API

​Module Includes

​Additional Files

​Exit Codes

​Box Lock

​Examples

​Hardware Test Script Example

​Notes

​Installing Python packages

Syntax

Global Options

Basic Usage

Environment Variables

Setting Variables

Auto-Injected Variables

File Downloads

Detached Mode

Killing Running Scripts

Port Forwarding

Timeout

Structured Output

Box-Side API

Module Includes

Additional Files

Exit Codes

Box Lock

Examples

Hardware Test Script Example

Notes

Installing Python packages