Embedded Lab Control (labctl)

Centralized management system for embedded development lab resources. Provides deterministic USB serial access, power control, and resource tracking for multiple single-board computers (SBCs).

Features

• Deterministic USB Serial Naming - udev rules create stable /dev/lab/<sbc> symlinks
• Remote Serial Console - TCP access via ser2net with multi-client support
• Smart Plug Power Control - Supports Tasmota, Kasa, and Shelly devices
• Web Dashboard - Browser-based monitoring and control
• REST API - Programmatic access to all features
• Health Monitoring - Automated ping, serial, and power checks
• Activity Stream - Unified audit trail with CLI tailing, live web feed, and API queries
• Hardware Claims - Exclusive-access coordination for long-running SBC workflows
• Session Logging - Capture serial output with rotation and compression
• Authentication - Session-based web login and API key auth (optional, disabled by default)
• Claude Code Skill - an example /deploy-and-test skill orchestrates build, deploy, boot, and serial capture over MCP (install)

Installation

Prerequisites

• Linux, Python 3.10+. Some extras need newer Python: Kasa devices that use KLAP v2 authentication need 3.11+ (python-kasa 0.12), and the sdwire extra installs nothing below 3.12 (SDWire commands then say so).
• ser2net for remote serial consoles (sudo apt install ser2net).

Install from PyPI

The distribution is embedded-lab-control; the command is labctl. With pipx (its own virtual environment, labctl on your PATH):

pipx install "embedded-lab-control[web,mcp,kasa,sdwire,actuators]"

or with pip, in a virtual environment:

python3 -m venv ~/.venvs/labctl
~/.venvs/labctl/bin/pip install "embedded-lab-control[web,mcp,kasa,sdwire,actuators]"

Pick the extras you need; the core package (SBC records, serial ports, ser2net, Tasmota and Shelly plugs, claims) needs none:

A command whose extra is missing says which one to install, e.g. pip install "embedded-lab-control[web]", or with pipx, pipx inject embedded-lab-control "flask>=3.0" "flask-socketio>=5.0".

labctl runs on built-in defaults; to configure it, start from config/labctl.yaml.example (also in the source distribution) saved as ~/.config/labctl/config.yaml (see Config file search order).

The PyPI package is the CLI and services' code only. The shared, system-wide install with systemd services (scripts/install-services.sh) runs from a git checkout; see Systemd Services.

Install from source

# System packages
sudo apt install python3-venv ser2net

# Clone repository
git clone https://github.com/johnjezl/Embedded-Lab-Control.git
cd Embedded-Lab-Control

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install with the extras you need (see the table above)
pip install -e ".[web,mcp,kasa,sdwire,actuators]"

# Copy example config (a personal config; see "Config file search order")
mkdir -p ~/.config/labctl
cp config/labctl.yaml.example ~/.config/labctl/config.yaml

Serial device names

Deterministic /dev/lab/<name> serial names come from udev rules generated from the adapters you register:

labctl serial discover                 # find adapters and their USB paths
labctl serial add board1-console 1-2.1 # name the adapter on USB path 1-2.1
labctl serial udev > 99-lab-serial.rules   # generate the rules
cat 99-lab-serial.rules                    # check: rules, not a message
sudo install -m 644 99-lab-serial.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger

The devices are root:dialout 0660: join dialout to open them directly (sudo usermod -aG dialout $USER, then log in again). On a system-wide install, install-services.sh makes the rules file writable by the labctl group (root:labctl 0664), and members of that group can update it with labctl serial udev --install --reload, without sudo; on such a host use that instead of the sudo install above, which resets the file to root:root 0644. Prefer --install wherever you can write the file: it refuses to remove or re-point a link a board claimed by someone else uses, while installing a file by hand checks nothing, so look at labctl claims list first.

docs/HARDWARE_MAP.md walks through finding USB paths, registering adapters, installing the rules and troubleshooting.

Config file search order

labctl uses the first of these that loads. A file in the search path that exists but can't be loaded (bad YAML or a bad value) is skipped with a warning, and the next one is used; a file named with -c or $LABCTL_CONFIG is refused instead. labctl web and labctl mcp --http refuse to start on any config that didn't load.

1. -c/--config PATH (only that file)
2. $LABCTL_CONFIG
3. ~/.config/labctl/config.yaml (or $XDG_CONFIG_HOME/labctl/config.yaml)
4. /etc/labctl/config.yaml
5. Built-in defaults

Warning: a personal ~/.config/labctl/config.yaml wins over the shared /etc/labctl/config.yaml. On a system install, a personal config left over from a personal install silently points labctl at a different database than the services use. Remove it, or pass -c /etc/labctl/config.yaml. Either way, you must be in the labctl group: install-services.sh makes /etc/labctl readable only by it (sudo usermod -aG labctl $USER, then log in again). Without that, labctl can't read the shared config and falls back to the built-in defaults and a personal database. To write the services' database too, its file and directory must be writable by the group. A new install's database (/var/lib/labctl/db/labctl.db) is; move an older one there (see Moving the database), or run commands as sudo -u labctl labctl ....

Quick Start

# Add an SBC
labctl add rpi4 --description "Raspberry Pi 4"

# Assign its console serial port (type: console, jtag or debug)
labctl port assign rpi4 console /dev/lab/rpi4 --baud 115200

# Assign a power plug (Tasmota example)
labctl plug assign rpi4 tasmota 192.168.1.100

# View status
labctl status

# Connect to serial console
labctl console rpi4

# Control power
labctl power on rpi4
labctl power cycle rpi4 --delay 5

# Start web dashboard
labctl web --port 5000

CLI Reference

Every command has --help. This section lists the commands; see docs/OPERATIONS.md for what each one changes.

Global Options

Common Flags

SBC Management

Activity Stream

Claims (Exclusive Access Coordination)

A claim's deadline moves each time you use the board. Long operations keep a claim you already hold alive while they run (CLI boot-test; MCP boot_test, serial_capture, sdwire_update, flash_image) and never claim a board for you. A boot test stops between runs once your claim is lost or someone else claims the board, reporting Result: INCOMPLETE, ... (or Result: STOPPED before the first run ...) instead of a pass rate; claim it for the whole test.

SDWire (SD Card Multiplexer)

Partition numbers are 1-based (e.g., -p 1 for the first partition, which maps to /dev/sdb1). ls, cat and info borrow the card: they switch it to the host and back, and refuse while the SBC is powered on.

SDWire operations shell out (via sudo) to mount, umount, dd, sync, partprobe, parted and blkid. They do not use sd-mux-ctrl, and they do not require a fixed privileged mountpoint such as /mnt/sdwire.

To reduce friction for interactive use and MCP/service flows, add a narrowly scoped sudoers rule. Use its own file: scripts/install-services.sh rewrites /etc/sudoers.d/labctl.

echo '<user> ALL=(root) NOPASSWD: /usr/bin/mount, /usr/bin/umount, /usr/bin/dd, /bin/dd, /usr/bin/sync, /bin/sync, /usr/sbin/partprobe, /sbin/partprobe, /usr/sbin/parted, /sbin/parted, /usr/sbin/blkid, /sbin/blkid' | sudo tee /etc/sudoers.d/labctl-sdwire
sudo chmod 440 /etc/sudoers.d/labctl-sdwire

Keep this scoped to the exact commands above. NOPASSWD sudo is still privileged; the point here is to allow SDWire workflows without granting broader root access.

Serial Device Management

Boot Testing

Serial Console

Power Control

Relays, Bindings and Recovery

USB relays ("actuators") can drive board straps and buttons: recovery mode, boot select, reset. An actuator channel is bound to an (SBC, purpose) pair. Only the lcus1_serial driver is implemented so far; it needs the actuators extra (pyserial).

pre_power bindings (--phase pre-power) are straps that must be in place before the board gets power. Every power-on (power on, power cycle, power-all on, the reboot after sdwire flash/update, boot-test, MCP and REST) first checks those relays on the board and on every board sharing its outlet. If a relay can't be reached, nothing is switched. labctl then drives each relay to its desired state and only then applies power. If a strap fails after a cycle's power-off, the boards are left off rather than booting without it. There is no --phase post-power yet (bindings stored with it by older versions are listed as inactive). When the monitor daemon starts, it returns unheld relay channels to their default state and leaves asserted bindings alone.

Multi-Client Access

Use labctl proxy start <sbc> when several people need to watch the same console. The proxy keeps viewers attached across normal SBC restarts and is view-only unless you opt in with --allow-write. While a proxy is active, labctl connect and labctl console refuse direct access for that SBC so people do not silently bypass the shared session.

Health Monitoring

User Management

MCP Server (AI Integration)

Shell Completion

eval "$(labctl completion bash)"   # or zsh; fish: labctl completion fish > ~/.config/fish/completions/labctl.fish

Aliases

For convenience, common aliases are supported:

• ls → list
• rm, delete → remove
• show → info
• on → power on
• off → power off

Configuration

Default config location: ~/.config/labctl/config.yaml

System installs use /etc/labctl/config.yaml. That file contains credentials and is intended to be group-readable by the labctl group, not world-readable. Any user who should run labctl against the shared lab inventory must be added to the labctl group and start a new login session afterward.

serial:
  dev_dir: /dev/lab          # udev symlink directory
  base_tcp_port: 4000        # lowest auto-assigned ser2net TCP port
  default_baud: 115200

ser2net:
  config_file: /etc/ser2net.yaml
  enabled: true

# Authentication (disabled by default)
auth:
  enabled: false
  secret_key: "generate-a-random-string"
  session_lifetime_minutes: 480
  users:
    - username: admin
      password_hash: "generate with: labctl user hash-password"
      api_key: "generate with: labctl user generate-key"

# HTTPS (disabled by default)
web:
  cert_file: "/etc/labctl/ssl/cert.pem"
  key_file: "/etc/labctl/ssl/key.pem"

# TP-Link Kasa credentials (for KLAP-authenticated devices)
kasa:
  username: "your-tplink-email@example.com"
  password: "your-tplink-password"

database_path: ~/.config/labctl/labctl.db
log_level: WARNING

# SQLite tuning. WAL journal mode is always on; this controls how long
# a transaction will wait for an exclusive lock before giving up.
database:
  timeout_seconds: 10.0

Note on backups: WAL mode creates -wal and -shm sidecar files next to labctl.db. Backup scripts should copy all three together, or quiesce the daemon and run sqlite3 labctl.db 'PRAGMA wal_checkpoint(TRUNCATE)' before copying just the main file.

Web Interface

Start the web server:

labctl web --port 5000

Access at http://localhost:5000

Features:

• Dashboard with SBC status overview
• Power control buttons
• Web-based serial console (xterm.js)
• Live /activity page backed by Server-Sent Events
• Claim badges on the dashboard and SBC detail pages; changes to a board someone else has claimed are refused (operators may override, logged)
• Settings and configuration view
• Optional login authentication (enable auth.enabled in config)
• Optional HTTPS with SSL/TLS certificates

Enabling HTTPS

labctl supports native HTTPS via SSL/TLS certificates. This is recommended when authentication is enabled, to protect credentials in transit.

1. Generate a self-signed certificate:

sudo mkdir -p /etc/labctl/ssl
sudo openssl req -x509 -newkey rsa:4096 -nodes \
  -keyout /etc/labctl/ssl/key.pem \
  -out /etc/labctl/ssl/cert.pem \
  -days 365 \
  -subj "/CN=labctl"

To include additional hostnames or IPs (recommended for avoiding browser warnings on your local network):

sudo openssl req -x509 -newkey rsa:4096 -nodes \
  -keyout /etc/labctl/ssl/key.pem \
  -out /etc/labctl/ssl/cert.pem \
  -days 365 \
  -subj "/CN=labctl" \
  -addext "subjectAltName=DNS:labctl,DNS:tarrasque,DNS:tarrasque.local,IP:192.168.1.100"

2a. Use via CLI flags (ad-hoc):

labctl web --cert /etc/labctl/ssl/cert.pem --key /etc/labctl/ssl/key.pem

2b. Or configure in config.yaml (persistent, recommended for systemd):

web:
  cert_file: "/etc/labctl/ssl/cert.pem"
  key_file: "/etc/labctl/ssl/key.pem"

3. Set permissions for the systemd service:

sudo chown root:labctl /etc/labctl/ssl/key.pem
sudo chmod 640 /etc/labctl/ssl/key.pem
sudo systemctl restart labctl-web

Access at https://localhost:5000. Your browser will warn about the self-signed certificate — this is expected for lab use.

REST API

Base URL: http://localhost:5000/api (or https:// when SSL is configured)

When authentication is enabled, API requests require an X-API-Key header:

curl -H "X-API-Key: your-api-key" https://localhost:5000/api/sbcs

For self-signed certificates, use curl -k or --cacert cert.pem to bypass certificate verification:

curl -k -H "X-API-Key: your-api-key" https://localhost:5000/api/sbcs

Key activity and claims endpoints:

POST /sbcs/<name>/power takes {"action": "on"|"off"|"cycle"}, plus an optional delay for a cycle (seconds, 0–86400; the default and the minimum are the largest stored cycle delay among the boards on the plug outlet, a board without one counting as 3.0) and "override_claim": true to act on a board another user has claimed. Power-on and cycle set the pre_power relays first (see Relays, Bindings and Recovery). Responses:

See docs/OPERATIONS.md for the full claim and REST error codes.

MCP Server (AI Integration)

labctl includes an MCP (Model Context Protocol) server for AI assistant integration. This allows tools like Claude Desktop and Claude Code to manage lab resources directly.

Install the MCP dependency from a checkout (the [mcp] extra):

pip install -e ".[mcp]"
# or from PyPI: pip install 'embedded-lab-control[mcp]'

Resources (read-only data): lab://sbcs, lab://sbcs/{name}, lab://power/{name}, lab://serial-devices, lab://sdwire-devices, lab://ports, lab://health/{name}, lab://status, lab://claims, lab://claims/{name}, lab://claims/history/{name}, lab://claims/metrics, lab://activity/recent, lab://activity/{name}

Tools (actions): power_on, power_off, power_cycle, run_health_check, add_sbc, remove_sbc, update_sbc, assign_serial_port, assign_power_plug, set_network_address, sdwire_to_dut, sdwire_to_host, sdwire_update, flash_image, serial_capture, serial_send, boot_test, list_images, delete_image (and more: see the docs)

Uploads: clients upload builds over HTTP to the MCP server (PUT /images/<name>, same API key) and pass the bare name to flash_image, sdwire_update or boot_test, so an agent can build on another machine (Uploading images).

Prompts: debug_sbc (guided SBC debugging), lab_report (comprehensive status)

See docs/MCP_SERVER.md for full tool parameters and usage.

Safety: destructive tools (power off, flashing, serial_send, deletions, …) act only when called a second time with a confirmation token; host files are reachable only under directories you allowlist in mcp.allowed_*_paths (none by default); the HTTP transport binds loopback and requires the web users' API keys (Authorization: Bearer) when auth.enabled is set. See Security Considerations.

Claude Desktop / Claude Code Configuration

For several Claude Code agents sharing the lab (each with its own API key, so claims keep them apart), see Connecting Claude Code agents.

For a single local client over stdio, add to your MCP client configuration (reading /etc/labctl/config.yaml requires the labctl group; otherwise point -c at your own config):

{
  "mcpServers": {
    "labctl": {
      "command": "/opt/labctl/venv/bin/labctl",
      "args": ["-c", "/etc/labctl/config.yaml", "mcp"]
    }
  }
}

Claude Code skill: /deploy-and-test

skills/deploy-and-test.md is an example skill that builds, deploys over SDWire, power-cycles and checks the serial console using the labctl MCP tools. It is not active in this repository. Claude Code loads a skill from a SKILL.md file, with name/description frontmatter, inside a directory named after the skill. To install it for one project (or for all your projects, under ~/.claude/skills/):

mkdir -p <your-project>/.claude/skills/deploy-and-test
cp skills/deploy-and-test.md <your-project>/.claude/skills/deploy-and-test/SKILL.md

It expects a connected labctl MCP server, and reads per-target settings from .claude/deploy-config.json.

Systemd Services

Install labctl system-wide with systemd services:

sudo ./scripts/install-services.sh

# Optional: MCP server over HTTP on 127.0.0.1:8080
sudo systemctl enable --now labctl-mcp

install-services.sh creates the labctl user and group and installs labctl with the web,mcp,kasa,sdwire extras into /opt/labctl/venv, linked as /usr/local/bin/labctl. It sets up /etc/labctl/config.yaml (root:labctl, 640) and /var/lib/labctl, and makes the udev rules file, /etc/ser2net.yaml and the services' database writable by the labctl group. A new config puts the database in /var/lib/labctl/db (setgid 2775, the file 664); if database_path names another file, the script leaves it alone and prints how to move it there. It writes /etc/sudoers.d/labctl for udevadm and systemctl restart ser2net. It enables and starts labctl-web and labctl-monitor; labctl-mcp is installed but not enabled. For USB relays, also install the actuators extra into the venv (sudo /opt/labctl/venv/bin/pip install "<checkout>[actuators]").

labctl-mcp runs labctl mcp --http 8080, which binds 127.0.0.1. To reach it from other machines, enable auth.enabled with API keys and override the command in a drop-in (sudo systemctl edit labctl-mcp). The drop-in must clear ExecStart before setting it again:

[Service]
ExecStart=
ExecStart=/opt/labctl/venv/bin/labctl -c /etc/labctl/config.yaml mcp --http 8080 --host 0.0.0.0

To update an existing install after git pull (keeps config and database):

sudo ./scripts/update.sh

When the configured database is /var/lib/labctl/db/labctl.db (also when written through a symlinked /var/lib/labctl), both scripts keep it (and its directory) writable by the labctl group, and make sure group members can traverse /var/lib/labctl: they add group search (g+x) when it belongs to the labctl group, and warn when members still can't reach it (e.g. it belongs to another group). Otherwise they print a note and leave the database alone.

Moving the database

Installs from before the /var/lib/labctl/db directory keep the database elsewhere (e.g. /var/lib/labctl/labctl.db or /var/lib/labctl/.config/labctl/labctl.db), which only the labctl user can write. To let labctl group members write it from the CLI, move it:

Every step runs as root: your own account may not be able to see into /var/lib/labctl at all.

sudo systemctl stop labctl-web labctl-monitor labctl-mcp
OLD=/var/lib/labctl/labctl.db          # your current database_path (named labctl.db)
sudo install -d -o labctl -g labctl -m 2775 /var/lib/labctl/db
# A clean stop normally leaves no -wal/-shm; move them too if present.
sudo sh -c 'for f in "$1" "$1-wal" "$1-shm"; do
    if [ -e "$f" ]; then mv -v "$f" /var/lib/labctl/db/; fi
done' sh "$OLD"
# Check the database arrived before going on: if it isn't there,
# update.sh creates a new, EMPTY database at the new path.
sudo ls -l /var/lib/labctl/db/labctl.db
# Set database_path: /var/lib/labctl/db/labctl.db, then copy the config to
# the service copy (update.sh refuses to run while the two differ):
sudoedit /etc/labctl/config.yaml
sudo -u labctl cp /etc/labctl/config.yaml /var/lib/labctl/.config/labctl/config.yaml
sudo ./scripts/update.sh   # or install-services.sh: sets 2775/664, restarts
sudo systemctl start labctl-web labctl-monitor   # and labctl-mcp if you use it

update.sh restarts the enabled services itself; the last line covers any you started by hand. As a group member, a write such as labctl claim <sbc> -r test then labctl release <sbc> should now work without sudo -u labctl.

Development

# Run tests
pytest tests/ -v

# Format code
black src/ tests/
isort src/ tests/

# Lint
flake8 src/ tests/

Documentation

• Implementation Plan - Development roadmap and status
• Mapping USB Serial Adapters - Stable /dev/lab names from USB paths
• Decision Log - Architecture decisions
• MCP Server - AI integration, security model
• Claude Code Agents - One API key per agent, setup and launch
• Operations - What every command and tool changes
• Security Policy - Reporting vulnerabilities
• Releasing - Publishing a version to PyPI

License

MIT