Skip to main content

​
Synopsis

crucihil agent --rig <path> [options]

​
Description

crucihil agent starts a persistent daemon on the bench machine. The agent:
  1. Loads the rig TOML and connects all configured backends
  2. Establishes a WebSocket connection to the cloud control plane
  3. Listens for run_suite commands pushed from the cloud
  4. Executes tests and syncs results back to the cloud via the WebSocket
  5. Caches results locally in SQLite when the cloud is unreachable, syncing on reconnect
The agent is a long-running process — it exits only on Ctrl-C or a fatal error. In production, it runs as a systemd service.

​
Options

​
--rig
path
required
Path to the rig TOML config. The file must exist. Short form: -r.
​
--cache
path
default:"~/.crucihil/results.db"
Path to the local SQLite result cache. Created if it does not exist. Results are written here first, then synced to the cloud on connection.
​
--verbose
boolean
default:"false"
Enable debug logging including WebSocket frames and backend I/O. Short form: -v.

​
Cloud connection

The agent connects to the cloud when [rig.cloud] is present in the rig TOML: 
[rig.cloud]
url                = "https://your-crucihil-server.example.com"
registration_token = "your-REGISTRATION_TOKEN-here"
On first boot with a registration_token, the agent:
  1. Calls POST /api/v1/rigs/register with the token
  2. Receives a permanent API key
  3. Saves the key to ~/.crucihil/credentials.toml
  4. Connects the WebSocket using the new key
On subsequent boots, the agent reads the saved key from credentials — no token needed. Without a [rig.cloud] section, the agent runs in local-only mode: tests can be triggered via crucihil run but the cloud dashboard and MCP tools will not see this rig.

​
WebSocket protocol

The agent maintains a single persistent WebSocket connection to /ws/agent on the control plane. The protocol uses JSON messages:
DirectionMessage typeDescription
Agent → Cloudagent_helloSent on connect — rig name, version, hardware summary
Cloud → Agentrun_suiteTrigger a test run — suite path, tags, suite type
Agent → Cloudrun_startedNotifies cloud that a run has begun — run ID
Agent → CloudresultPer-test result — status, duration, errors, signals
Agent → Cloudrun_finishedRun complete — final summary
Cloud → Agentcancel_runCancel the currently running suite
The connection uses JWT auth. If the connection drops, the agent reconnects with exponential backoff. Queued runs that arrived while the agent was offline are redelivered by the cloud on reconnect.

​
Local result cache

Results are written to the SQLite cache before being synced to the cloud. This ensures no results are lost even if the cloud is unreachable during a test run. The sync happens automatically when the WebSocket reconnects. The cache path defaults to ~/.crucihil/results.db. Override with --cache.

​
Production deployment with systemd

CruciHiL ships a systemd template unit for running the agent as a service.

​
Install the service

# From the crucihil repo
sudo bash scripts/install-agent.sh
This installs systemd/crucihil-agent@.service to /etc/systemd/system/.

​
Enable for a rig

# Enable and start the agent for a specific rig TOML
sudo systemctl enable --now crucihil-agent@bench_01
The @bench_01 suffix maps to rigs/bench_01.toml — the unit file looks for the TOML at /opt/crucihil/rigs/<instance_name>.toml.

​
Service unit

[Unit]
Description=CruciHiL Agent — %i
After=network.target

[Service]
Type=simple
User=crucihil
WorkingDirectory=/opt/crucihil
ExecStart=/opt/crucihil/.venv/bin/crucihil agent --rig rigs/%i.toml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

​
Check status

sudo systemctl status crucihil-agent@bench_01
sudo journalctl -u crucihil-agent@bench_01 -f

​
Environment variables

The agent respects these environment variables for cloud connectivity:
VariableDescription
CRUCIHIL_BASE_URLCloud control plane URL (overrides [rig.cloud].url)
CRUCIHIL_API_KEYAPI key (overrides saved credentials)

​
Example startup output

$ crucihil agent --rig rigs/bench_01.toml

Starting agent — rig: rigs/bench_01.toml
2026-06-03 10:14:22 INFO  crucihil.agent: rig loaded — bench_01 (orin_nx)
2026-06-03 10:14:22 INFO  crucihil.agent: connecting backends...
2026-06-03 10:14:22 INFO  crucihil.hal.backends.peak: opened can0 @ 500 kbit/s
2026-06-03 10:14:22 INFO  crucihil.hal.backends.socketcan: opened can1 @ 250 kbit/s
2026-06-03 10:14:22 INFO  crucihil.agent: connecting to cloud...
2026-06-03 10:14:23 INFO  crucihil.agent: connected — ws://crucihil-server.fly.dev/ws/agent
2026-06-03 10:14:23 INFO  crucihil.agent: ready (local-only: no)

​
Exit codes

CodeMeaning
0Clean shutdown (Ctrl-C)
2Fatal error (bad TOML, backend failure, missing credentials)

​
See also