SpudSuiteHelp Open SpudSuite

Agents

Installing a runner

A runner is the small program that does your workflows' work, on a machine you choose. Install one on your laptop to try things out, and on a server, Docker host or Kubernetes cluster for work that should keep running. Every install command is on the Runners page, filled in for your workspace.

The Runners page, with the install commands
The Runners page, with the install commands

Runners only ever call out to SpudSuite over HTTPS, so they work behind firewalls and on home networks with nothing to open. You need to be a workspace admin to connect one, or to approve one someone else installed.

macOS and Linux

In a terminal:

curl -fsSL https://agents.spudsuite.com/install.sh | sh

The installer puts the spud command on your machine (it installs Python tools with uv, so there's nothing else to set up) and adds a desktop shortcut. On a desktop, the SpudSuite Runner app then opens in your browser. Sign in and pick your workspace, and the runner is paired.

On a server with no desktop, the runner prints a short code and a link instead. A workspace admin opens the link and approves the code (see Pairing).

Windows

In PowerShell:

irm https://agents.spudsuite.com/install.ps1 | iex

It does the same as on macOS and Linux: installs spud, adds a desktop shortcut and opens the runner app to pair.

The runner app

The runner app is a small page on your own machine, at http://127.0.0.1:7317, opened from the desktop shortcut or with spud app. Use it to pair, start and stop the runner, change its settings (name, labels, how many runs at once), and keep the runner's secrets. Nothing in it is reachable from other machines.

Pairing

  • From the runner app: sign in and pick the workspace.
  • From a terminal: run spud runner pair agents.spudsuite.com. It shows a code like ABCD-EFGH and a link. A workspace admin opens the link (or Agents β€Ί Runners), checks the code matches, and chooses Approve.

Approving a runner's pairing code
Approving a runner's pairing code

Keep it running

The install command sets up the runner's keeper: a small program your computer starts whenever you sign in (a sign-in task on Windows, a launchd agent on macOS, a systemd user service on Linux). The keeper starts the runner, starts it again if it stops, and installs updates. You don't need to do anything else.

On a server without a desktop, pair the runner first, then start the keeper. The install command prints the exact line, and does both for you when you run it in a terminal.

The runner won't start as an administrator or root, because every thread and step would get those rights too. Run it as an ordinary user, or run it in Docker. If a server really must run it as root, set SPUDSUITE_RUNNER_ALLOW_ADMIN=1.

If you installed the runner before the keeper existed, run the install command again, once. It keeps the runner's pairing, secrets and history, and moves it under the keeper. The runner's page tells you when a runner still needs this.

Docker

For Docker, a workspace admin first makes a registration token on the Runners page (under Registration tokens). It lets containers join without anyone approving a code. Then:

docker build -t spudsuite-runner https://agents.spudsuite.com/downloads/spudsuite-runner-docker.tar.gz
docker run -d --name spudsuite-runner --restart unless-stopped -v spudsuite-runner:/data -v spudsuite-runner-home:/home/spud \
  -e SPUDSUITE_SITE=https://agents.spudsuite.com \
  -e SPUDSUITE_REGISTRATION_TOKEN=ssreg_... spudsuite-runner

The second volume keeps the runner's home folder, /home/spud, so tools threads install there (such as .NET in ~/.dotnet), caches and work in progress survive an update. Only /tmp starts empty. If your container was started without it, add -v spudsuite-runner-home:/home/spud the next time you recreate it.

Behind a company proxy or antivirus that inspects HTTPS, also mount its certificate (a PEM file): add -v /path/to/company-ca.pem:/etc/spudsuite/ca.pem:ro, and the runner, Claude Code, git and gh trust it.

To let threads in it build images and run containers (docker build, docker run, with Podman inside the container), tick Let threads run containers under the command on the Runners page. The command then fetches a seccomp profile and adds what Podman needs, and nothing more: never --privileged or your Docker socket.

curl -fsSLO https://agents.spudsuite.com/downloads/spudsuite-runner-seccomp.json
docker run -d --name spudsuite-runner --restart unless-stopped -v spudsuite-runner:/data -v spudsuite-runner-home:/home/spud \
  --security-opt seccomp=spudsuite-runner-seccomp.json --security-opt apparmor=unconfined --device /dev/net/tun \
  -v spudsuite-runner-containers:/home/spud/.local/share/containers -e SPUDSUITE_CONTAINERS=1 \
  -e SPUDSUITE_SITE=https://agents.spudsuite.com -e SPUDSUITE_REGISTRATION_TOKEN=ssreg_... spudsuite-runner

See Run in Docker for what that changes and what to expect. Runner 0.1.39 and later. It doesn't work on Kubernetes yet.

The volume keeps the runner's credential and secrets, so it stays the same runner across restarts. If you remove that runner in SpudSuite and start the container again with a new registration token, it notices SpudSuite no longer accepts the credential on the volume and registers as a new runner with the token (runner 0.1.31 and later). You can also set SPUDSUITE_RUNNER_NAME, SPUDSUITE_RUNNER_LABELS (comma-separated) and SPUDSUITE_RUNNER_CAPACITY (runs at once, 4 by default). With Docker Compose, after building the image:

services:
  runner:
    image: spudsuite-runner
    restart: unless-stopped
    environment:
      SPUDSUITE_SITE: https://agents.spudsuite.com
      SPUDSUITE_REGISTRATION_TOKEN: ssreg_...
      SPUDSUITE_RUNNER_NAME: docker
      SPUDSUITE_RUNNER_LABELS: docker
    volumes:
      - runner-data:/data
volumes:
  runner-data:

Kubernetes (Helm)

Build the image as for Docker and push it to a registry your cluster can pull from. Then, with a registration token:

helm install runners https://agents.spudsuite.com/downloads/spudsuite-runner-chart.tgz \
  --set site=https://agents.spudsuite.com \
  --set registrationToken=ssreg_... \
  --set image.repository=<your registry>/spudsuite-runner

Each pod registers as its own runner, named after the pod, and keeps its credential on its own volume. Useful settings:

Setting What it does
replicas How many runners (pods) to run
capacity Runs each one takes at once (4)
labels Labels runs can ask for (kubernetes)
existingSecret Use a Secret you made (key token) instead of registrationToken
sandbox The default sandbox: local runs script and agent steps in the runner's pod; kubernetes starts a pod for each
extraSandboxes More sandboxes it offers, such as [e2b]; runs that ask for one go only to runners that have it
sandboxConfig Each sandbox's settings on this runner, such as {e2b: {domain: …, api_key_secret: E2B_KEY}}; keys stay on the runner
resources, persistence.size, nodeSelector, tolerations The usual Kubernetes knobs

Updates

The Runners page shows each runner's version, and says when a newer one is available. For each runner, choose how it updates:

  • Update when asked: a workspace admin chooses Update when it suits them.
  • Update automatically: it updates itself when a new version comes out.

Either way, a runner finishes the runs and Factory threads it's on first (and takes no new ones meanwhile), then hands the update to its keeper. The keeper checks the new version's files, installs it in its own folder beside the old one (nothing that's running gets replaced), switches over, and waits for the new version to check in with SpudSuite. If it doesn't within two minutes, or it keeps stopping, the keeper puts the old version back. Each step shows on the runner's page as it happens, along with the runner's own log if it was rolled back. A runner in a container can't replace itself. Its page shows the commands to run instead, ready to copy:

docker build -t spudsuite-runner https://agents.spudsuite.com/downloads/spudsuite-runner-docker.tar.gz
docker rm -f spudsuite-runner
docker run -d --name spudsuite-runner --restart unless-stopped -v spudsuite-runner:/data -v spudsuite-runner-home:/home/spud -e SPUDSUITE_SITE=https://agents.spudsuite.com spudsuite-runner

If the runner's threads run containers, the commands keep the flags for that. They build the new image, then replace the container and keep its volume, so the runner stays paired and keeps its secrets, trusted certificates, Claude Code's sign-in and its threads' sessions (runner 0.1.35 and later keep the last two on the volume). You don't need a registration token, and you can run them again safely. If you named the container or the volume something else, use your names.

Remove a runner

On the Runners page, choose Remove next to it. It stops taking runs straight away, runs it was holding are marked lost, and its credential stops working. To use the machine again, pair it again. On the machine itself, spud runner unpair forgets the credential.

Check on it

spud runner status says whether the runner is paired and can reach SpudSuite. spud --version shows its version.

To see what it's doing, open its page in SpudSuite: Working on now lists the threads and runs it holds, and when it last checked in (see Runners). On the machine, its log says the same. In Docker, run docker logs -f spudsuite-runner. From runner 0.1.41, the log has a line when each turn starts (its thread and project), still working once a minute while it runs, and how it ended: finished (done) with its time and cost, or failed with why. Workflow runs and assistant replies get the same start and end lines. Every 5 minutes there's an Alive line saying what it holds and when it last reached SpudSuite.

Let it work on your own computer

On your own desktop, a runner can also let Factory and Agents work on your files, inside a sandbox, in the folders you choose. See Personal runner.

Something unclear, or out of date? Spud wants to know: tell us from SpudSuite and we'll fix the page.