Guides
Record a run and play it back
Keep everything a fleet says during a run in a file, then play it back to watch on the page, or read it as text, to work out what happened. The recorder listens; it never sends anything to the fleet it records.
You need the broker up (scripts/broker up), or a broker that takes logins and a login that may read the fleet.
Record
scripts/record start # fleet desk; --fleet lab for another
# ... the run ...
scripts/record stop
The recording is a new file in recordings/, named for the fleet and when it started (UTC):
desk-20261022-143245.jsonl. It’s written a message at a time, so a crash or a pulled cable loses nothing already
heard. recordings/ is kept out of git.
Everything on the fleet’s topics goes in, as heard: each bot’s hello, status, telemetry, events and the commands it was sent, poses, the station’s summary and notices, the e-stop, and what clients asked the station for. The fleet’s state when recording started (the retained hellos, statuses and e-stop) is the first thing in it.
On a broker that takes logins, the recorder login reads everything. The command is in Run the programs with a
login.
Find one
scripts/record list
desk-20261022-143245.jsonl fleet desk, started 2026-10-22T14:32:45Z, 0:11, 448 messages, bots: sim-1, sim-2
Read it as text
scripts/record show desk-20261022-143245.jsonl # everything
scripts/record show desk-20261022-143245.jsonl --topic '*/event' # every bot's events
scripts/record show desk-20261022-143245.jsonl --topic 'sim-1/*' # one bot
A line each: seconds since the start, the topic, the message. (retained) marks the state it started from.
Watch it on the page
Playback sends the messages again, at the times they were heard, into another fleet (replay unless --into says
otherwise). The page watches that fleet like any other.
scripts/viewer up # if it isn't already
scripts/record play desk-20261022-143245.jsonl
Open http://127.0.0.1:8080/?fleet=replay in your browser to watch it.
--speed 2plays it twice as fast;--from 30 --until 90plays seconds 30 to 90. Started from the middle, it first sends the fleet as it was then (the latest hello, status, telemetry and pose of each bot), so the page isn’t empty until the next message.- Ctrl-C stops it.
It refuses to play into the fleet it was recorded on, and into a fleet with anything online or anything live on it. A bot there could act on a played-back command, and a station there would argue with the recording’s. It also refuses when the broker doesn’t accept its login or won’t let it read that fleet, since then it can’t tell. It sends nothing retained, so nothing is left behind when it ends.
On the cluster’s broker, no login may publish to another fleet, so play back on the development broker
(scripts/broker up) and point the page at it.
The file
JSON Lines: a header, then a message a line.
{"gunkslab_recording": 1, "protocol": "v0", "fleet": "desk", "started": "2026-10-22T14:32:45Z"}
{"t":0.05,"topic":"sim-1/hello","msg":{"type":"gl-zero", ...},"retained":true}
{"t":0.085,"topic":"sim-1/telemetry","msg":{"up_ms":2305, ...}}
t is seconds since the recording started, topic the part after gunkslab/v0/<fleet>/. A cleared retained
message has "msg": null; one that wasn’t JSON keeps its text as "raw". Any tool that reads JSON Lines can take
it apart.