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 this for an attached run; 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

The box holds the box lock for as long as the detached job runs and releases it when the job ends. See locking.

Killing Running Scripts

# Kill with default SIGTERM
lager python --box my-lager-box --kill

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

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

When a script exceeds the timeout:

First, SIGTERM is sent (exit code 124)
If the script doesn’t exit, SIGKILL is sent (exit 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:

# .lager (in project root)
includes:
  my_lib: /path/to/my_lib
  fixtures: /path/to/fixtures

The CLI searches up the directory tree for a .lager file, 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
-1	Failed to retrieve exit code from box
124	Script terminated by SIGTERM (timeout)
137	Script killed by SIGKILL (timeout, force)
Other	Script’s own exit code

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 --box my-lager-box --kill

# 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]
After script execution, the hardware cache on the box is automatically cleared to release VISA connections
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

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

​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

Examples

Hardware Test Script Example

Notes

Installing Python packages