Agents
Run in Docker
Docker mode runs the whole SpudSuite Runner inside Docker on your computer: the runner, Claude Code, Factory threads and every Agents step. The runner's keeper stays on your computer and looks after the container. Threads then can't see your home folder, keychain, ssh keys, other projects or your other programs, and they never get administrator rights on your computer, even if you are an administrator.
You can switch back at any time. The runner works without Docker too.
Turn it on
- Install Docker Desktop on macOS or Windows, or Docker on Linux, and start it.
- Install the runner with its install command (see Install a runner) and pair it.
- In the runner app, under Docker mode, choose Run in Docker. From a terminal:
spud runner docker on.
The keeper builds the runner's image (a few minutes the first time), brings the runner's pairing and secrets into Docker, and restarts the runner there. If it can't, the runner keeps running on your computer and the runner's page in Agents βΊ Runners says why.
Then sign Claude Code in once more, from the runner app: the sign-in on your computer stays there.
Behind a proxy that inspects HTTPS
Some company networks and antivirus programs inspect HTTPS with a certificate of their own, which your computer trusts and a fresh container doesn't. Signing Claude Code in, git and gh then fail with SELF_SIGNED_CERT_IN_CHAIN. The keeper hands your computer's trusted certificates to the container each time it starts it (from the System keychain on macOS, the trusted roots on Windows, the system bundle on Linux), so this works on its own with runner 0.1.33 and keeper 1.2.0 or later.
You can also add the certificate on the runner's page in SpudSuite, under Trusted certificates (see Runners). If the certificate isn't in your computer's trusted roots (on macOS, the System keychain), save it as a PEM file named ca.pem in the runner's folder (on macOS ~/Library/Application Support/SpudSuite Runner, on Windows %APPDATA%\SpudSuite Runner, on Linux ~/.config/spudsuite-runner), then run spud runner docker off and spud runner docker on. Ask IT for the file if you don't have it. Keeper 1.2.1 and later.
Let threads run containers
Threads and Agents steps can build images and run containers inside the runner's container, with the usual docker commands: docker build, docker run, docker run -p 5432:5432 postgres. It's Podman underneath, running as the thread's own user, so it never gets privileged mode or your computer's Docker. It's off until you turn it on.
- In SpudSuite, open the runner's page under Agents βΊ Runners.
- Under Containers, tick Allow containers.
The runner passes it to its keeper, and the keeper checks with SpudSuite and restarts the runner's container with what Podman needs. The runner waits until it has no runs or threads at work, so nothing gets cut off, and the page says On once it's ready. Untick it to turn it off the same way. It needs runner 0.1.39 and keeper 1.3.0 or later, which update by themselves.
What changes for the runner's container when you turn it on:
- Its seccomp profile lets user namespaces and the mounts inside them through. The kernel still refuses those calls outside a thread's own namespace.
- Docker's AppArmor rule against mounts is off (Linux computers only; Docker Desktop on macOS and Windows has no AppArmor).
- It gets
/dev/net/tun, for the containers' own networks.
It still runs without privileged mode, without your Docker socket, with the same few capabilities and with no new privileges. Code in a thread can reach more of the Linux kernel than before, so turn it on for runners whose threads need containers.
What to expect:
- Images and build caches stay in the runner's Docker volume, so they survive restarts and updates. They count towards Docker's disk, so
docker system prunein a thread clears them. - Ports a container publishes (
-p 8080:80) are on the runner container'slocalhost, where the thread can reach them. They aren't on your computer. psin a container lists the runner container's processes too, and memory and CPU limits (--memory,--cpus) don't apply inside.docker composeisn't included.- Behind a proxy that inspects HTTPS, pulls work with the runner's trusted certificates, and containers a thread runs trust them too. A
docker builddoesn't: in a Dockerfile that downloads over HTTPS, point the tool at/etc/spudsuite-trust/bundle.pem, for exampleRUN SSL_CERT_FILE=/etc/spudsuite-trust/bundle.pem pip install -r requirements.txt. - If Docker on your computer can't start the container this way, the runner starts without containers and its page says why.
For a runner you started yourself with the Docker install command, tick Let threads run containers under the command on the Runners page instead. It adds the same flags to the command, plus a volume for images; on the runner's page, the command is under Containers.
Where your projects are
Factory projects live in SpudSuite Docker in your home folder, so you can open them on your computer. To use another folder: spud runner docker on --factory ~/Work/factory.
What it stops, and what it doesn't
| Without Docker | In Docker | |
|---|---|---|
| Your home folder, keychain and ssh keys | Reachable (personal mode limits this) | Out of reach |
| Other projects and programs | Reachable | Out of reach |
| Administrator rights on your computer | Refused: the runner won't start as an administrator | Out of reach |
| The runner's own credential | Readable | Out of reach: threads run as their own user |
| The internet and your local network | Open | Open |
| Containers in threads | Your computer's Docker, if threads can reach it | Off, or Podman inside the runner's container with Allow containers |
Threads still get what they need to work: GitHub and Claude Code's sign-ins, and the project folder.
What it costs
- Docker Desktop, which is paid for larger companies.
- About 2 to 4 GB of memory while Docker runs, and about 2 GB of disk for the image.
- Builds in project folders run somewhat slower on macOS and Windows.
- Personal mode's folder grants, the tray icon and local models on your graphics card don't apply inside Docker.
Commands
spud runner docker on # run in Docker
spud runner docker status # on or off, and where projects are
spud runner docker off # run on this computer again
spud runner status # works the same in Docker
Only your computer can switch Docker mode off. Nothing inside the container can.