Skip to main content
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

OptionShortTypeDefaultDescription
--box TEXTStringLagerbox name or IP address
--image IMAGEStringlagerdata/gatewaypy3:v0.1.84Docker image to use
--env FOO=BARMultipleSet environment variables for the script
--passenv VARMultiplePass environment variables from current shell
--killFlagTerminate a running Python script
--signal SIGNALChoiceSIGTERMSignal to use with --kill
--download FILEMultipleDownload files from box after script completes
--allow-overwriteFlagAllow overwriting existing local files with --download
--timeout SECONDSInteger0 (none)Maximum runtime in seconds
--detach-dFlagRun in detached mode (background)
--port PORT-pMultipleForward ports to the Python process
--add-file FILEMultipleAdd extra files to upload with script
--helpFlagShow help message and exit
Arguments:
  • RUNNABLE - Python script file or directory to execute (required unless --kill is used)
  • ARGS - Additional arguments passed to the script
Signal choices for --kill: SIGINT, SIGQUIT, SIGABRT, SIGKILL, SIGUSR1, SIGUSR2, SIGTERM, SIGSTOP

​
Basic Usage

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

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

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

​
Environment Variables

​
Setting Variables

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

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

​
Auto-Injected Variables

The following environment variables are automatically available inside your script:
VariableDescription
LAGER_OUTPUT_CHANNELFile path for structured output (see Structured Output below)
LAGER_PROCESS_IDUnique UUID for this execution
LAGER_RUNNABLEPath to the script being executed
LAGER_BOXBox 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-box --download results.csv

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

# Allow overwriting existing local files
lager python test.py --box my-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-box --detach
In detached mode:
  • The command returns immediately after the script starts
  • No stdout/stderr is streamed back
  • The script continues running on the box
  • Use --kill to stop it later

​
Killing Running Scripts

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

# Kill with specific signal
lager python --box my-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-box -p 8080

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

# Forward with protocol
lager python server.py --box my-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-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:
EncoderIDUse Case
OutputEncoders.Raw1Binary data (images, files)
OutputEncoders.Pickle2Python objects (default)
OutputEncoders.JSON3JSON-serializable data
OutputEncoders.YAML4YAML-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-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-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 CodeMeaning
0Success
-1Failed to retrieve exit code from box
124Script terminated by SIGTERM (timeout)
137Script killed by SIGKILL (timeout, force)
OtherScript’s own exit code

​
Examples

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

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

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

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

# Kill running script
lager python --box my-box --kill

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

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

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

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

​
Hardware Test Script Example

# test_power.py - run with: lager python test_power.py --box my-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

  • Default Docker image: lagerdata/gatewaypy3:v0.1.84
  • 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)

​
pip Command

Run pip commands in the Python container on the box. Useful for installing packages that your scripts depend on.

​
Syntax

lager pip [OPTIONS] [ARGS]...

​
Options

OptionDescription
--box BOXLagerbox name or IP address
--helpShow help message and exit

​
Examples

# Install a package
lager pip install pandas --box my-box

# List installed packages
lager pip list --box my-box

# Uninstall a package
lager pip uninstall numpy --box my-box

# Install from requirements file
lager pip install -r requirements.txt --box my-box

​
Notes

  • Runs pip in the Lager Python container, not on your local machine
  • Installed packages persist across lager python invocations on the same box
  • All standard pip commands and arguments are supported