Project
Install checklist
Run before every release, on a fresh machine for each platform below: a new virtual machine, or a new user account with nothing from gunkslab on it. It checks what a stranger meets, from an empty machine to driving a simulated bot, using only the docs. Each run’s result goes in the table at the end, and anything that went wrong goes on Known issues.
The platforms
| # | Platform | Runtime | Run the commands in |
|---|---|---|---|
| A | macOS 26 or later, Apple silicon | Apple’s container |
Terminal |
| B | macOS 26 or later, Apple silicon | Docker Desktop (RUNTIME=docker if container is also there) |
Terminal |
| C | Windows 11 | Docker Desktop, WSL2 integration on | a WSL2 Ubuntu shell, the repo cloned inside WSL (~/), not on C: |
| D | Ubuntu LTS | docker, or podman | a terminal |
| E | Red Hat family (RHEL, Fedora, Rocky or Alma) | podman | a terminal |
The steps
Write down the OS version and the runtime’s version first. Start a timer at step 2: the target is 15 minutes from step 2 to step 6.
-
The runtime. Install it as Install says, and nothing else. Anything the page doesn’t say, but you had to do, is a finding.
-
The repo.
git cloneit andcd gunkslab, as Install says. -
The check.
scripts/check-protocolprints15 schemas, all examples as expected. -
The doctor.
./gunkslab doctorendsnothing to fix, and its first check names the runtime you meant to use. -
Up.
./gunkslab upendsgunkslab: up, 2 simulated bots.and the page opens in the browser. On a platform that can’t open one (the doctor says so), it prints the address: open it yourself. -
Drive. On the page:
- two bots, sim-1 and sim-2, on the desk;
- pick sim-1 in the drive panel: the arrow keys and the on-screen pad move it;
- click a spot on the desk: the bot drives there itself;
- the e-stop stops both, and clearing it lets them move again.
Stop the timer.
-
Status, logs, version.
./gunkslab status: fouroklines and the page’s address;./gunkslab logs: four files inlogs/;./gunkslab version: the version being released.
-
Recover.
scripts/station crash, then./gunkslab doctor:FIX not running: station;./gunkslab down && ./gunkslab up: up again;- the doctor:
nothing to fix.
-
Down.
./gunkslab down, then./gunkslab doctor:nothing runningandnothing to fix. -
The tutorials’ start. Tutorial 01’s and 03’s commands work as written. A stranger runs tutorial 03 unaided for G1; this step only checks the commands.
A run passes when every step does, as written, within the 15 minutes. Anything else is a finding: put the step, what you saw and what fixed it on Known issues, and in an issue.
The runs
| Date | Version | # | OS and runtime, with versions | Fresh? | Steps 2–6 | Result | Findings |
|---|---|---|---|---|---|---|---|
| 2026-10-25 | 0.1.0-dev | B | macOS 27.0.1, Docker Desktop with Docker Engine 20.10.7 | no: a dev machine, images partly cached | 36 s to step 5 | steps 3–5 and 7–9 pass; 6 not run (needs a person at the page) | none |
| 2026-10-25 | 0.1.0-dev | D | Ubuntu 24.04.5 LTS, Docker 28.4.0 | gunkslab’s part: no clone or images before; the runtime was there; the repo from a git bundle (it’s private) | 14 s to step 5 | steps 3–10 pass: 6 with the page in a Mac’s browser, through an SSH tunnel; 6 and 10 later the same day, on main at 89cf790 | one, not a fault: a go-to boxed into a corner ends blocked, as tutorial 07 says; backing out of a dead end comes after G1 |
| 2026-10-25 | 0.1.0-dev | E | Rocky Linux 9.8, podman 5.8.2 (through its docker command), SELinux enforcing |
as D | 28 s to step 5, after the fixes | first run: 3 and 5 failed, SELinux refusing the containers the repo’s files; 4 called a taken port free (no nc). After the fixes: 3–5 and 7–10 pass (10 later the same day, on main at 89cf790); 6 not run |
three, fixed: mounts take z under SELinux; the port check uses ss or lsof without nc; up checks each piece is still running |
| 2026-11-11 | 0.1.0-dev | A | macOS 27.0.1, Apple’s container 0.11.0 |
no: a dev machine; gunkslab’s images removed first, the build cache kept | 12 s to step 5 | all ten pass, at e65d34f (main with tutorial 03’s new order); 6 by a script driving the page in a headless Chrome, not a person | none |
| 2026-11-11 | 0.1.0-dev | B | macOS 27.0.1, Docker Desktop with Docker Engine 20.10.7 | no: a dev machine, two of gunkslab’s images cached | 29 s to step 5 | all ten pass, at e65d34f; 6 as A | none |
| 2026-11-11 | 0.1.0-dev | D | Ubuntu 24.04.5 LTS, Docker 28.4.0 | gunkslab’s part: no clone or images before; the runtime was there; the repo from a git bundle | 16 s to step 5 | all ten pass, at e65d34f; 6 as A, with the page in a Mac’s browser through an SSH tunnel | one: over SSH, with no screen, the doctor said a browser can be opened (fixed the same day: it now says there’s no screen) |
| 2026-11-11 | 0.1.0-dev | E | Rocky Linux 9.8, podman 5.8.2 (through its docker command), SELinux enforcing |
as D | 29 s to step 5 | all ten pass, at e65d34f; 6 as A, the browser in a Playwright container on the same machine (its SSH allows no tunnels) | none |
| 2026-11-11 | 0.1.0-dev | C | none | none | none | not run: no Windows 11 machine to hand; 0.1.0 will ship with Windows listed as not tried yet | none |
| 2026-11-14 | 0.1.0-dev | A | macOS 27.0.1, Apple’s container 0.11.0 |
no: a dev machine; gunkslab’s images removed first, the build cache kept | 60 s for steps 2–6 | all ten pass, at 9393e11 (main after the move to the new project); 6 by a script driving the page in a headless Chrome, not a person | none |
| 2026-11-14 | 0.1.0-dev | B | macOS 27.0.1, Docker Desktop with Docker Engine 20.10.7 | no: a dev machine; gunkslab’s images removed first | 68 s for steps 2–6 | all ten pass, at 9393e11; 6 as A | none |
| 2026-11-14 | 0.1.0-dev | D | Ubuntu 24.04.5 LTS, Docker 28.4.0 | gunkslab’s part: no clone or images before; the runtime was there; the repo from a git bundle | 59 s for steps 2–6 | all ten pass, at 9393e11; 6 as A, with the page in a Mac’s browser through an SSH tunnel | none |
| 2026-11-14 | 0.1.0-dev | E | Rocky Linux 9.8, podman 5.8.2 (through its docker command), SELinux enforcing |
as D | 52 s for steps 2–6 | all ten pass, at 9393e11; 6 as A, the browser in a Playwright container on the same machine | none |
| 2026-11-14 | 0.1.0-dev | C | none | none | none | not run: still no Windows 11 machine to hand; 0.1.0 ships with Windows listed as not tried yet | none |