Run a remote lab agent
Publish one or more card rigs to a team, so an operator can discover what exists, take exclusive hold of a rig for the length of a session, and stream APDUs to it -- without every user needing the rig's own Card Bridge token.
On this page
The agent does not replace Card Bridge over SSH.
It sits in front of it: the data plane is still the Card Bridge HTTP /apdu
relay, and the agent adds identity, rig inventory, status, and exclusive
session locking on top.
operator --control--> Lab agent :8700 (who exists, may I have it)
operator --stream---> rig proxy :8801 --> Card Bridge :8642 --> reader
Use this when several people share a set of rigs. For a single operator and a single reader, plain Card Bridge over SSH is less machinery.
Prerequisites
- YggdraSIM installed on the agent host (
yggdrasim-lab-agentships with the base install; the YAML parser is a base dependency) - one reachable Card Bridge
/apduendpoint per rig, already working per Card Bridge over SSH - a private network path, or SSH forwards, between operators and the agent
The agent binds loopback by default. Treat a non-loopback bind the same way you would treat exposing Card Bridge itself: see Security rules.
Mint access tokens
The config stores only SHA-256 hashes, never the token itself. Generate a pair with the shipped helpers:
python -c "
from yggdrasim_common.card_bridge_auth import generate_token
from yggdrasim_common.remote_lab.security import hash_token
token = generate_token()
print('token :', token)
print('token_hash :', hash_token(token))
"
Give the token to the operator and put the token_hash in the config. A
role: admin token additionally permits force-release.
Two kinds of rig
A rig declares what it offers, and that decides which way APDUs travel.
| Kind | Holds the card | Holds a modem | The operator |
|---|---|---|---|
card |
the rig | no | streams APDUs to the rig |
modem |
the operator | yes, plus a SIMtrace2 | offers a card for the rig to drive |
A card rig is the original shape and stays the default: leave kind
out and nothing changes. A modem rig reverses the direction. It has
no card of its own, so a reservation must carry a card offer naming a
Card Bridge the rig can reach, and the rig runs a HIL supervisor against
it for the length of the session.
A host that carries both a reader and a modem publishes two rigs sharing one lock name, so taking either takes the bench.
Write the config
agent:
id: lab-01
name: Bench lab
bind_host: 127.0.0.1
control_port: 8700
defaults:
reservation_timeout_seconds: 30
heartbeat_timeout_seconds: 60
max_session_seconds: 14400
security:
access_tokens:
- id: alice
token_hash: "sha256:0000000000000000000000000000000000000000000000000000000000000000"
role: user
- id: lab-admin
token_hash: "sha256:1111111111111111111111111111111111111111111111111111111111111111"
role: admin
rigs:
- id: bench-a
name: Bench A
location: TestLocality
tags: [pcsc, esim]
capabilities: [scp03, scp11]
enabled: true
stream_proxy:
bind_host: 127.0.0.1
external_port: 8801
upstream:
url: http://127.0.0.1:8642/apdu
token_file: ~/.config/yggdrasim/card_bridge/8642.token
Field notes, all enforced by the loader:
| Key | Required | Behaviour |
|---|---|---|
agent.id |
yes | rejected when empty |
agent.bind_host |
no | defaults to 127.0.0.1 |
agent.control_port |
no | defaults to 8700 |
agent.public_host |
no | the host callers are told to use. Not enforced anywhere: left unset, the agent answers each caller with the address that caller used, which is the right setting for a rig reachable by more than one route |
defaults.* |
no | 30 / 60 / 14400 seconds; floored at 1 |
security.access_tokens |
yes | at least one entry; token_hash must start with sha256:; role is user or admin |
rigs[].id |
yes | must be unique, compared case-insensitively |
rigs[].stream_proxy.external_port |
yes | rejected when it collides with another rig or with agent.control_port on an overlapping bind |
rigs[].stream_proxy.bind_host |
no | defaults to 127.0.0.1 |
rigs[].stream_proxy.public_host |
no | overrides agent.public_host for this rig's stream URL; falls back to the Host header, then bind_host, with 0.0.0.0 rewritten to 127.0.0.1 |
rigs[].upstream |
yes | either url, or host + port (+ optional scheme); /apdu is appended when missing |
rigs[].locks |
no | defaults to rig:<id>; give two rigs a shared lock name when they cannot run at once |
rigs[].enabled |
no | defaults to true |
rigs[].kind |
no | card or modem; defaults to card, so a config written before modem rigs existed is unchanged |
rigs[].modem.label |
no | what an operator sees in the inventory; defaults to the rig name |
rigs[].modem.simtrace_vidpid |
no | defaults to 1d50:60e3 |
rigs[].consumer.enabled |
no | defaults to false; must be true before a reservation may start a supervisor on this host |
rigs[].consumer.supervisor |
no | defaults to yggdrasim-hil-supervisor; the only executable a reservation can start |
rigs[].consumer.simtrace_reset |
no | off, usb-reset, port-power or auto; defaults to usb-reset |
rigs[].consumer.bridge_host / .bridge_port |
no | where the rig-side HIL bridge listens; 127.0.0.1 and 9997 |
rigs[].consumer.apdu_timeout_ms |
no | defaults to 30000, which suits a card reached across a tunnel |
On a modem rig stream_proxy and upstream are both omitted: the rig
serves no card, so it binds no listener and has no upstream to name.
Declaring an upstream on a modem rig, or a modem or consumer block
on a card rig, is rejected rather than ignored.
rigs:
- id: quectel-a
name: Quectel bench
kind: modem
location: TestLocality
modem:
label: Quectel EC25-E
simtrace_vidpid: 1d50:60e3
consumer:
enabled: true
simtrace_reset: usb-reset
locks: [bench:pi-1]
upstream.url must be http(s) with no credentials, query, or fragment.
Use upstream.token_file rather than inline token so the Card Bridge
bearer stays in a 0600 file.
Start the agent
yggdrasim-lab-agent --config ~/.config/yggdrasim/remote-lab.yaml
--log-level DEBUG raises verbosity. A malformed config fails at startup
with the offending key path, so a typo never produces a half-open agent.
Run it as a service
An unattended rig host runs the agent and its Card Bridge as systemd --user
units. Two examples ship beside the HIL one:
mkdir -p ~/.config/systemd/user
cp guides/systemd/yggdrasim-card-bridge.service.example \
~/.config/systemd/user/yggdrasim-card-bridge.service
cp guides/systemd/yggdrasim-lab-agent.service.example \
~/.config/systemd/user/yggdrasim-lab-agent.service
systemctl --user daemon-reload
systemctl --user enable --now yggdrasim-card-bridge.service yggdrasim-lab-agent.service
loginctl enable-linger "$USER"
enable-linger is what makes the units start at boot without a login.
Never order a unit after default.target when that target already wants
it. The agent is ordered after the Card Bridge, and both are
WantedBy=default.target; adding After=default.target to either one closes
a cycle, and systemd resolves a cycle by deleting one of the start jobs. The
result is a unit that silently never starts at boot while systemctl status
afterwards reports nothing worse than inactive (dead).
systemctl --user enable --now does not catch this, because starting a unit
by hand never runs the boot transaction. Rehearse the boot path instead:
systemctl --user stop yggdrasim-lab-agent.service yggdrasim-card-bridge.service
systemctl --user start default.target
systemctl --user is-active yggdrasim-card-bridge.service yggdrasim-lab-agent.service
journalctl --user -b | grep -i "ordering cycle"
Both units should report active and the grep should find nothing.
Reach the agent
Pick one of two shapes. They differ in who the rig is meant to serve, not in how callers authenticate -- an access token is required either way.
Pin a name, or echo the caller
A rig's advertised stream URL comes from stream_proxy.public_host, then
agent.public_host, then the request's Host header, then the bind
address. Only the last is rewritten, 0.0.0.0 becoming 127.0.0.1.
Pinning a name is right for a rig that answers to exactly one. Leaving both unset is right for a rig reachable more than one way, because the agent then hands each caller back the address that caller reached it on:
called as esim-rig.example.test -> http://esim-rig.example.test:8801/apdu
called as 10.73.184.89 -> http://10.73.184.89:8801/apdu
That matters when a host is reachable over a VPN and over a LAN, or when it later becomes a VPN peer in its own right. A pinned name that resolves to an address the caller cannot route is the worst of both: the control port answers, every stream URL points somewhere unreachable, sessions open and APDUs go nowhere.
scripts/remote_lab_open_agent_to_vpn.py --public-host auto leaves the
field unset for you; passing a name pins it as before.
A shared rig on a VPN
When a rig is meant to serve everyone who holds a token and the device config, put it on the VPN the team already runs (NetBird, Tailscale, WireGuard, a routed office LAN) and bind the agent to a real interface:
agent:
bind_host: 0.0.0.0
public_host: rig-host.internal.example # resolvable BY CALLERS
rigs:
- id: bench-a
stream_proxy:
bind_host: 0.0.0.0
public_host: rig-host.internal.example
public_host is not optional here. The agent advertises a stream URL for each
rig, and it derives the host from stream_proxy.public_host, then
agent.public_host, then the request's Host header, then bind_host --
rewriting 0.0.0.0 to 127.0.0.1 on the way. Leave it unset and control calls
succeed while every caller is handed a loopback stream URL it cannot reach, so
sessions open and APDUs go nowhere.
Point the device registry at the same name rather than at 127.0.0.1, and
prefer the DNS name over an address so a DHCP lease change does not strand it.
The rig's card-bridge upstream stays on loopback: only the agent talks to it, and it runs on the same host.
scripts/remote_lab_open_agent_to_vpn.py makes both edits on the rig host. It
backs the config up, validates it with the agent's own loader before touching
the service, and restores the backup if that fails:
python3 scripts/remote_lab_open_agent_to_vpn.py --dry-run
python3 scripts/remote_lab_open_agent_to_vpn.py --public-host rig-host.internal.example
From an operator machine, scripts/remote_lab_verify_over_vpn.sh checks the
whole path and separates a network problem from a bind problem -- the two
failures the GUI renders identically. It is read-only and never prints the
token:
scripts/remote_lab_verify_over_vpn.sh rig-host.internal.example path/to/device.token
A single-operator rig over SSH
When the rig serves one person, keep it loopback-bound and forward the control port and every rig's stream port. Let SSH notice a dead peer rather than hang on one:
ssh -fN -o ExitOnForwardFailure=yes -o ServerAliveInterval=15 -o ServerAliveCountMax=3 \
-L 8700:127.0.0.1:8700 -L 8801:127.0.0.1:8801 user@rig-host
The forward dies with the remote host, so a rig-host reboot leaves nothing listening locally and the agent reads as unreachable while it is in fact healthy. Re-open the tunnel before diagnosing anything further. This is the shape that strands a rig the moment the tunnel drops, which is why a shared rig belongs on a VPN instead.
Take a session
Every control call except /healthz needs an access-token bearer.
AGENT=http://127.0.0.1:8700
TOKEN=<the token you minted>
curl -s "$AGENT/healthz"
curl -s -H "Authorization: Bearer $TOKEN" "$AGENT/api/v1/rigs" | jq .
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"user":"alice","client_id":"bench-laptop","requested_ttl_seconds":3600}' \
"$AGENT/api/v1/rigs/bench-a/sessions" | jq .
A successful reservation returns 201 with the session identity and the
stream endpoints:
{
"session_id": "...",
"session_token": "...",
"rig_id": "bench-a",
"expires_at": "2026-07-25T12:00:00Z",
"heartbeat_interval_seconds": 10,
"stream": {
"transport": "http-card-bridge",
"url": "http://127.0.0.1:8801/apdu",
"status_url": "http://127.0.0.1:8801/status",
"card_reset_url": "http://127.0.0.1:8801/card/reset"
}
}
A rig already held by someone else returns 423 Locked with the holder in
the body. That is the whole point of the agent: two operators cannot drive
one card at the same time.
Keep the session alive at heartbeat_interval_seconds:
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d "{\"session_token\":\"$SESSION_TOKEN\"}" \
"$AGENT/api/v1/sessions/$SESSION_ID/heartbeat"
Release it when done:
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d "{\"session_token\":\"$SESSION_TOKEN\"}" \
"$AGENT/api/v1/sessions/$SESSION_ID"
Release requires the session_token in the body, so holding an access token
is not enough to drop somebody else's session. That is what force-release
is for.
A session that stops heartbeating expires on its own after
heartbeat_timeout_seconds, and no session outlives max_session_seconds.
An admin token can evict a stuck holder:
curl -s -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
-H 'Content-Type: application/json' -d '{}' \
"$AGENT/api/v1/rigs/bench-a/force-release"
Stream APDUs through the session
The per-rig proxy speaks the Card Bridge protocol, so existing consumers
work unchanged -- the bearer is the session_token, not the rig's own Card
Bridge token:
printf '%s' "$SESSION_TOKEN" > ~/.config/yggdrasim/card_bridge/8801.token
chmod 600 ~/.config/yggdrasim/card_bridge/8801.token
python main/main.py \
--remote-card-url http://127.0.0.1:8801/apdu \
--remote-card-token-file ~/.config/yggdrasim/card_bridge/8801.token
The proxy exposes /ping (unauthenticated), /status, /apdu, and
/card/reset. Requests without a live session are rejected with 401, so a
released or expired session cannot keep driving the card.
Store a host once
A registered device is a host card, and it records everything about the box rather than about a run. Two doors can be recorded on one card:
| Field | Door | Notes |
|---|---|---|
agent_host, agent_control_port, token file |
agent | bearer token, shared, reservable |
ssh_target, ssh_identity_file |
SSH | this operator's login, for setup and single-operator use |
remote_workdir, remote_python, hil_service_name |
SSH | where the checkout and its service live on the host |
card_reachability, card_url |
either | tunnel opens a reverse forward; direct points the host at a card published on a routable address |
A host you have not set up yet
An invite carries an agent and a token, so there is no invite for a host that has neither. That is the ordinary state of a rig before somebody installs an agent on it, and it is exactly the host you want to record while preparing one.
Remote Bridge stores that host directly: fill the SSH fields, name it,
and add it. The card then carries only the SSH half, reports itself as
ssh-only rather than offline, and offers no Connect, because there is
no agent to reserve a rig from. Importing an invite for the same host
later fills in the agent half without changing its identity.
A host needs at least one door. Neither half is rejected, and so is half an agent: a host without a port would build a control URL nobody can call.
The SSH half never travels in an invite. An invite hands a colleague an agent and a token; it must not hand them your login or the path to your private key.
Naming a host card is what collapses the Remote Bridge action from a screenful of fields to one choice: every field it used to ask for is a property of the box. Typed values still win, so the card fills blanks rather than overriding an answer.
Both surfaces then report one view of the host. Starting a Remote Bridge setup asks the host's agent whether its bench is already held and stops before touching anything when it is, so two operators cannot configure conflicting supervisors on one box. That check closes the setup window; the lasting exclusion while a rig runs is the card lease.
Offer a card to a modem rig
The rig has to reach the Card Bridge you name, so open a reverse tunnel before reserving unless the bridge is already published on an address the rig can route to:
ssh -fN -R 8642:127.0.0.1:8642 esim@rig.example.test
yggdrasim-lab --agent http://rig.example.test:8700 --token-file ~/.config/yggdrasim/remote_lab/alice.token \
reserve quectel-a --user alice --offer-card-url http://127.0.0.1:8642/apdu
The token for your own bridge is read from the file
yggdrasim-card-bridge wrote for that port, so it does not have to be
passed. Use --offer-card-token-file when the bridge runs somewhere
else.
Reachability is checked before the reservation is granted. A tunnel that
is not open fails here with a message saying so, rather than as silence
once the modem powers up. If the card is already leased, the reservation
is refused with card_leased and nothing starts.
The grant carries no stream block, because the card is already on your
machine and there is nothing for the agent to stream back. It carries a
consumer block instead, and the rig releases the card and stops the
supervisor when the session ends, expires or loses its heartbeat.
Control API reference
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /healthz |
none | liveness |
| GET | /api/v1/info |
access token | agent identity and version |
| GET | /api/v1/rigs |
access token | inventory with per-rig status |
| GET | /api/v1/rigs/{id}/status |
access token | one rig |
| POST | /api/v1/rigs/{id}/sessions |
access token | reserve; 423 when held |
| POST | /api/v1/sessions/{id}/heartbeat |
access token + session_token |
extend |
| DELETE | /api/v1/sessions/{id} |
access token + session_token |
release |
| POST | /api/v1/rigs/{id}/force-release |
admin token | evict the holder |
Use the GUI instead
The Universal GUI Command Center
consumes the same agents under /api/remote-lab: import an agent, list its
devices, read status, connect, release, and force-release. The client-side
inventory persists to Workspace/RemoteLab/registry.json; per-device tokens
live in their own private files, and export redacts them. A device's name,
location, tags and agent address are editable from its card.
Connect behaves like plugging in a local reader. It reserves the rig, starts
the heartbeat, reads the card's ATR from the relay's status endpoint and
publishes the reader as Remote Lab: <device name>; it does not scan the
card and it does not move the operator off the Remote Lab page. That
reservation is held by one link session that belongs to no module. The
file system, eSIM management, the local SM-DP+ and SCP80 each open their own
card channel through the published name when they need one, and closing any
of them leaves the rig reserved. Disconnect (or the agent expiring the
session) closes the link, which closes those channels first and releases the
rig last, so nothing outlives the reservation it was opened under.
The shells reach the same rig once the GUI has connected it. yggdrasim-scp03,
yggdrasim-scp11 and yggdrasim-scp11-live take --reader "Remote Lab: <device
name>" (an exact PC/SC reader name works there too); the SCP80 shell takes
set reader_name Remote Lab: <device name>, and set reader_idx N switches
back to a local reader. The MCP card tools accept the same name in
reader_name. A name that resolves to nothing is a startup error, never a
fallback to the first local reader.
Security rules
- Choose the bind to match who the rig serves. A single-operator rig stays on loopback behind SSH. A rig shared by everyone holding a token belongs on a trusted network -- a VPN or a routed internal LAN -- and binds to a real interface. What must never happen is a non-loopback bind on an untrusted network: the agent authenticates callers, but it is not a TLS terminator, so the transport has to be private on its own.
- Restrict reachability at the network layer when the VPN can do it. A NetBird or Tailscale ACL that exposes the control and stream ports only to a lab group beats the all-or-nothing reach an SSH login grants.
- Store only
token_hashin the config file. The config is not a secret store, and a hash is useless to an attacker who reads it. - Issue one access token per person, not one per team, so revoking a leaver is an edit and a restart rather than a rotation for everyone.
- Reserve
role: adminfor the people who should be able to yank a rig out from under a colleague mid-session. - Session tokens are as sensitive as Card Bridge tokens:
0600files, never shell history.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| agent exits at startup naming a key path | config schema error | fix the reported key; the loader reports the exact index, e.g. rigs[1].upstream |
duplicate stream proxy bind/port |
two rigs share a port, or one collides with agent.control_port |
give each rig its own external_port |
every control call returns 401 |
token not in security.access_tokens, or hash mismatch |
re-mint the pair and paste the new token_hash |
POST /sessions returns 423 |
rig held by a live session | wait for expiry, or force-release with an admin token |
/apdu returns 401 mid-run |
session expired because heartbeats stopped | heartbeat at heartbeat_interval_seconds |
| rig status reports the upstream down | Card Bridge not running or token wrong | validate the rig directly per Card Bridge over SSH |
force-release returns 403 |
bearer is a user token |
use a role: admin token |