Skip to content
gunkslab

Get started

Install

Get the repo, check you have a container runtime, and run one check to prove it all works.

1. Get the repo

The code is in early access, so ask for it first. Ask in the issue tracker. Asking needs a GitLab account, and a free one is fine. Tick Turn on confidentiality before you create the issue, so your request stays private. Once it’s approved, GitLab adds you to the project, and the reply gives you the repository’s address.

While you wait, you need git, and on Windows a Linux shell to run everything from. Pick your OS:

macOS

Run the check below. If git isn’t there, macOS offers to install its command line developer tools, which include git. Say yes, then run the check again.

Ubuntu / Debian

sudo apt install git

RHEL / Fedora

The same for Rocky Linux and AlmaLinux:

sudo dnf install git

Windows

gunkslab runs on Windows inside WSL2, Windows’ own Linux. Everything from here on happens in its Ubuntu shell.

In PowerShell, as administrator:

wsl --install

It installs WSL2 and Ubuntu. Restart when it asks, open Ubuntu from the Start menu, and pick a user name and password. Then, in the Ubuntu shell:

sudo apt install git
cd ~

Keep the repo in your WSL home folder (~), not on C: (/mnt/c/...). Microsoft advises keeping files in WSL’s own file system for speed, and the install checklist runs it there.

To check, whichever OS:

git --version

It prints git version and a number.

Once you have the address:

git clone <the address you were given>
cd gunkslab

git asks you to log in the first time. Use the account you were given access on.

If you already have a copy, update it instead:

git pull

2. Container runtime

Every service and tool here runs in a container. You need one container runtime and nothing else. The scripts find it themselves: they try container, then docker, then podman. To pick one, put RUNTIME= in front of the command, for example RUNTIME=podman scripts/broker up.

macOS

macOS 26 or later, on Apple silicon. Use Apple’s container, the runtime gunkslab is built on day to day. Docker Desktop works too.

Apple’s container. Download the signed installer from https://github.com/apple/container/releases and run it. Then start it:

container system start

Check it’s running:

container system status

You should see:

status             running

Docker Desktop. Use Docker’s installer and start Docker Desktop. If container is installed too, put RUNTIME=docker in front of each command.

Install checklist: Apple’s container and Docker Desktop passed, 2026-11-11.

Ubuntu / Debian

Ubuntu 24.04. Docker from Ubuntu’s own packages, with buildx. The scripts build their images with it, and without it every build fails:

sudo apt install docker.io docker-buildx
sudo usermod -aG docker $USER

Log out and back in, so docker works without sudo.

Debian 12. Debian’s Docker has no buildx, so use podman:

sudo apt install podman

podman needs no service and no group. It works on Ubuntu too, if you’d rather. Docker’s own packages (https://docs.docker.com/engine/install/debian/) include buildx, if you want Docker on Debian.

Install checklist: Ubuntu 24.04 passed with docker, 2026-11-11. Debian has no run recorded yet.

RHEL / Fedora

podman, from your distribution. The same for Rocky Linux and AlmaLinux:

sudo dnf install podman

There’s nothing to start. podman runs without a service. With SELinux on, the scripts mount the repo’s folders so containers may read them, so leave SELinux as it is.

Install checklist: Rocky Linux 9 passed with podman, 2026-11-11.

Windows

Windows 11, with Docker Desktop on WSL2.

  1. Install Docker Desktop with Docker’s installer, and start it. It runs on WSL2.

  2. In Docker Desktop, open Settings, then Resources, then WSL integration. Turn it on for Ubuntu, and click Apply.

  3. In the Ubuntu shell, check docker answers:

    docker version
    

    It should list a Server section. If it says it can’t connect, Docker Desktop isn’t running, or step 2 isn’t on for Ubuntu.

Docker’s page on it: https://docs.docker.com/desktop/features/wsl/.

Install checklist: not run yet, and 0.1.0 will ship without it. See Known issues.

3. Run the protocol checker

scripts/check-protocol

The first run downloads a small Python image, so it takes about a minute. You should see:

15 schemas, all examples as expected

What happened

  • The container. scripts/check-protocol started a throwaway Python container, mounted the repo’s protocol/ folder into it, and installed the one library the checker needs, jsonschema, inside it.
  • The check. It ran protocol/check.py, which tests every example message against the message layouts. The container was deleted when it finished.
  • Your machine. Nothing was installed on it. Python and the library only existed inside the container.

4. PlatformIO, for a real board

Skip this until you have a real board on the desk.

Everything above runs in containers. Flashing a board is the exception. It goes over USB, a container can’t reach the USB port, so PlatformIO goes on the machine itself. You need it for the bot’s firmware (a real bot on the bench) and for the bench programs.

macOS

With Homebrew:

brew install platformio

If no port appears when you plug the board in, install the USB-serial driver for its chip: Silicon Labs CP210x or WCH CH34x, depending on the batch. Both are free.

Ubuntu / Debian

pip install platformio doesn’t work here: Ubuntu 24.04 and Debian 12 keep pip away from the system’s Python. Use PlatformIO’s installer. It needs Python’s venv:

sudo apt install curl python3-venv
curl -fsSL -o get-platformio.py https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py
python3 get-platformio.py

Put pio on your path:

mkdir -p ~/.local/bin
ln -s ~/.platformio/penv/bin/pio ~/.local/bin/pio
ln -s ~/.platformio/penv/bin/platformio ~/.local/bin/platformio

Let yourself use the USB port, with PlatformIO’s rules for boards and the dialout group:

curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/system/99-platformio-udev.rules | sudo tee /etc/udev/rules.d/99-platformio-udev.rules
sudo udevadm control --reload-rules && sudo udevadm trigger
sudo usermod -aG dialout $USER

Log out and back in. The board shows up as /dev/ttyUSB0. On Ubuntu, if it shows in lsusb but /dev/ttyUSB0 never appears, brltty (a braille display service) took it. Remove it with sudo apt remove brltty, and plug the board in again.

RHEL / Fedora

PlatformIO’s installer:

curl -fsSL -o get-platformio.py https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py
python3 get-platformio.py

Put pio on your path:

mkdir -p ~/.local/bin
ln -s ~/.platformio/penv/bin/pio ~/.local/bin/pio
ln -s ~/.platformio/penv/bin/platformio ~/.local/bin/platformio

Let yourself use the USB port, with PlatformIO’s rules for boards and the dialout group:

curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/system/99-platformio-udev.rules | sudo tee /etc/udev/rules.d/99-platformio-udev.rules
sudo udevadm control --reload-rules && sudo udevadm trigger
sudo usermod -aG dialout $USER

Log out and back in. The board shows up as /dev/ttyUSB0.

Windows

PlatformIO goes in WSL, next to the repo, and the board’s USB port is handed to WSL with Microsoft’s usbipd. This hasn’t been tried on Windows yet.

  1. In the Ubuntu shell, install PlatformIO as on Ubuntu (the Ubuntu / Debian tab): the installer, pio on your path, and the dialout group.

  2. In PowerShell, install usbipd:

    winget install --interactive --exact dorssel.usbipd-win
    
  3. Plug the board in. In PowerShell, find it and share it, once per board (as administrator):

    usbipd list
    usbipd bind --busid <its BUSID>
    
  4. Each time you plug it in, hand it to WSL (no administrator needed), with the Ubuntu shell open:

    usbipd attach --wsl --busid <its BUSID>
    

    It shows up in the Ubuntu shell as /dev/ttyUSB0.

Microsoft’s page on it: https://learn.microsoft.com/windows/wsl/connect-usb.

Check it’s there:

pio --version

You should see PlatformIO Core, version 6.2.0 or later. CI and the containers build with 6.2.0. With the board plugged in, pio device list shows its port.

Next

You’re set up. Run the quickstart for a fleet on your desk in about five minutes, or start the tutorials from the top.