Agents
Runners
A runner is the program that does the work: it takes runs from the queue, runs their steps on its machine, and reports back. Install them on laptops, servers, Docker or Kubernetes, from the Runners page. A Free workspace connects one runner and runs two things at once, with 600 runner minutes a month; Pro has any number of runners and more of both (see Plans and billing). Over the limit, new runs wait in the queue and running ones finish. Your own computer in the SpudSuite app doesn't count as the one runner (see This computer). Once a Free workspace has its runner, Add a runner says so in place of the install commands; remove the runner to connect a different one.
Pairing
When a workspace admin copies the install command for macOS and Linux or Windows, it carries a one-time key, so the runner connects to the workspace as it installs and starts straight away, with no code to approve. Each key works once, for 24 hours, and shows under Registration tokens, where you can revoke it. Untick Connect it to this workspace straight away for a command without a key, to share more widely.
Without a key, a runner on a desktop opens the SpudSuite Runner app, where you sign in and pick this workspace. A runner on a server prints a short code and a link; a workspace admin opens the link and approves it. For Docker and Kubernetes, a workspace admin makes a registration token, which lets runners join without anyone approving a code. Revoke the token when you no longer need it.
The SpudSuite app for Windows pairs itself when you sign in, as a runner only you can send work to. See This computer.
Labels
Each runner has labels, such as gpu, linux or prod. Admins change them under Labels on the runner's page: type a label, press Enter, then choose Save labels. A run that asks for labels (with runner_labels when it starts) only goes to a runner that has them all. The assistant can be limited to runners with certain labels too, and so can a gateway: if only some runners can reach it, list their labels on the gateway (see Gateways and model policies).
A runner's page
Click a runner's name on the Runners page to open its page. It shows:
- Working on now: each Factory turn and workflow run the runner holds this minute, with its thread and project, how long it's been going, when the runner last said anything about it (Last heard) and when Claude Code last said or did something (Last output). A runner sends word about a turn at least once a minute, even when Claude Code is quiet, so a turn shows Working while that keeps coming, Quiet after a few minutes without it, and Not answering after ten; SpudSuite ends a turn after 15 minutes without word. Beside the heading, Checked in β¦ ago says when the runner last checked in at all. Click a turn to open its thread.
- how long it's been running, its runs over the last 7 days, how many succeeded, and how long a run takes on average
- its machine: CPU, memory and disk now, and a chart of CPU and memory over the last day (a runner sends these with its check-in every 5 minutes, and every few seconds while someone has its page open, which shows Live)
- Activity: two charts of what it ran over the last 24 hours, 7 days, 30 days or 90 days. What it ran splits its work by where it came from: Factory turns, workflow runs people started, runs from triggers, sub-workflows, evals and campaigns, and assistant replies. Models it used shows how many runs and turns used each model, such as Opus 5.5 or a local model; a run that used two models counts for each. Hover a bar for its numbers, or choose Show as a table.
- its Claude sign-in, its local models, its AI budget, its secrets, how it updates, and its recent runs
Anyone in the workspace can see the page. Only admins can change things on it.
Updates
When a new version of the runner comes out, the runner's page and the Runners list say so. Click Update to β¦ to update it now, or choose Update automatically when idle under Updates. An update waits for the runner's runs to finish, then the runner's keeper installs the new version beside the old one, checks it, and puts the previous version back if the new one doesn't check in. Updates shows what the keeper is doing as it happens, and why it rolled back if it did. You can also click Update in the runner app on the machine itself.
If Updates says Move this runner under the keeper, the runner was installed before the keeper existed. Run the install command it shows on that machine once. The runner keeps its pairing, secrets and history.
A runner in a container updates with its image instead: pull the new image, or helm upgrade with the new tag.
Claude on a runner
Agent steps and Factory turns use Claude Code on the runner. Under AI on the runner's page, choose how it signs in:
- A Claude account: click Sign in with Claude. The runner starts Claude Code's own sign-in, and a few seconds later the page shows Open Claude's sign-in page. Sign in there, copy the code Claude shows you, paste it into the box and click Finish signing in. The runner finishes signing in, and the page shows who's signed in. Claude Code needs to be installed on the runner first. Use the newest link: each Sign in with Claude starts a new sign-in, and a code from an earlier link won't work. If Claude Code turns the code away, the page shows what it said (runner 0.1.32 and later).
- An Anthropic API key: paste the key and click Set key.
- An LLM gateway (Portkey, LiteLLM and others): pick one of the workspace's gateways under Gateway. Claude Code then sends everything through the gateway's base URL, with its API key and headers, taken from secrets on the runner or the workspace's. The gateway can be type
anthropic, oropenai-compatiblewith Models for Claude Code filled in on its page (runner 0.1.32 or later translates for Claude Code). For Portkey: typeopenai-compatible, base URL ending in/v1, and a secret headerx-portkey-api-key. If only some runners can reach the gateway, keep it to them with labels (see Gateways and model policies). Background work through a gateway counts against the runner's pay-as-you-go caps, as with an API key.
The login stays on the runner. The code and the key are sealed in your browser with the runner's own key, so SpudSuite passes them on but can't read them. A Pro or Max plan is for one person, so only use it on your own runner. For a runner other people's runs use, choose an API key or a Team or Enterprise seat.
To sign out, click Sign out and confirm. Switch account signs in again with a different account.
Factory turns on any model
Factory turns run on Claude Code unless you choose otherwise. To run them on another model, such as one from OpenAI, Bedrock through Portkey, OpenRouter or your own model server, use the open harness: SpudSuite's own agent loop on the runner. It edits files, runs commands and git, and posts to threads the way Claude Code does, and it follows the same rules about which commands may run. Like Claude Code, it reads messages people send while it works; a long command still running when one arrives keeps going in the background, so the thread can read the message and decide whether to wait for it or stop it.
- Make a gateway for your model provider, if the workspace hasn't got one (see Gateways and model policies). Any type works:
openai-compatiblefor Portkey, LiteLLM, OpenRouter, vLLM and OpenAI itself, oranthropic. - On the runner's page, under Factory turns, set Factory turns run on to The open harness.
- Pick the Gateway, type the Model as the gateway names it (for example
gpt-4.1or@bedrock/us.anthropic.claude-sonnet-4), and choose Use the open harness.
The page says The open harness is ready once the runner has checked it can use the gateway. Leave Model empty if the gateway lists its Claude models, and threads that ask for Opus, Sonnet or Haiku use the matching model the gateway names. Threads on the runner's local models run on them through the open harness too. Each Factory project can also choose for itself (see Project settings). Turns through a gateway count against the runner's pay-as-you-go caps.
To go back, set Factory turns run on to Claude Code.
Secrets
Secrets live on the runner, in its own store. Workflows refer to them by name (secrets.<name>), and Gateway and Connection resources name the secret that holds their key.
The runner's page lists its secrets by name, never their values. To add one, type its name and value under Secrets on this runner and click Add secret. To change one, click Replace next to it. To delete one, click Remove. The value is sealed in your browser for that runner, so SpudSuite only ever sees the name. You can also set secrets in the runner app, or with the runner's command line on a server.
Trusted certificates
Some company networks and antivirus programs inspect HTTPS with a certificate of their own. A runner that doesn't trust it can't sign Claude Code in or reach GitHub, and you see errors such as SELF_SIGNED_CERT_IN_CHAIN. On the runner's page, under Trusted certificates, paste the certificate or click Choose a file (.pem, .crt or .cer), give it a name such as Office proxy, and click Add certificate. The runner takes it within a few seconds, and the page says In use on the runner. From then on the runner, Claude Code, git and gh trust it as well as the usual certificates. Click Remove to stop trusting it.
Add only the certificate, never its private key: SpudSuite turns a private key away. Your IT team can give you the certificate, or you can export it from your computer's keychain or certificate store. People who manage runners can add and remove certificates, and it needs runner 0.1.34 or later.
Containers
A runner in Docker can let its threads build images and run containers with docker, using Podman inside the runner's own container. On the runner's page, under Containers, tick Allow containers. It's off until you do, and it never gives the runner privileged mode or your computer's Docker. See Run in Docker for what it changes and what to expect. People who manage runners can turn it on.
Runner 0.1.42 and later check their own container and list what containers need under Containers: Podman, user namespaces (the seccomp profile), /dev/net/tun, and volumes for the home folder and for images. Anything missing shows with how to fix it. For a runner you started yourself with docker run or Compose, the card also gives the command that recreates its container with everything in place. Run it when no threads are working, because recreating the container stops whatever it's doing.
Capacity and leases
A runner takes up to its capacity of runs and Factory turns at once. It's 4 unless the runner was started with SPUDSUITE_RUNNER_CAPACITY set. To change it from SpudSuite, pick a number from 1 to 16 under At once on the runner's page, or Its own setting to go back. The runner picks it up within a few seconds (runner 0.1.41 and later; older runners can be held below their own number, but not raised above it). The workspace's plan also limits how many threads and runs go at once across all its runners. While it works on a run it holds a lease and renews it as it reports. If it stops reporting, for example because the machine went to sleep, the lease runs out and the run is marked lost.