Agents
Local models
A runner can run AI models on its own machine, so agent steps can work without sending anything to Claude. It works on the CPU alone, and uses the GPU when the GPU has room to spare. You choose, agent by agent, whether to use them.
Set them up
- Open the runner's page from Runners and find Local models. It shows the machine's cores, memory and graphics card, and the model it would start with.
- Click Set up local models. The runner downloads its own copy of Ollama, starts it, and downloads the model picked for that machine. The card shows the progress.
- When it says Local models ready, the model list shows each model, its size and whether it's loaded on the GPU or the CPU.
You need to be a workspace admin, and the runner needs to be version 0.1.17 or later. If Ollama is already running on the machine, the runner uses it and doesn't install another.
The runner's copy of Ollama only listens on that machine, and prompts and answers never pass through SpudSuite.
Choose models
- Add model: type a name, such as
qwen3:8b, or pick one from the suggestions, then click Add model. The runner checks there's room on its disk first. - Remove (the bin beside a model): deletes it from the runner.
- Default local model: the model agents use when they don't name one. Leave it on Picked for this machine to let the runner choose.
- Remove local models: stops Ollama and deletes it and every model it downloaded.
Smaller models are quicker but less capable. On a machine without a graphics card the runner suggests small models, or ones built from many small experts that still run quickly on a CPU.
Choose how agents use them
Each agent has a Local models setting, next to its model:
- Claude only: the agent uses its Claude model, as before.
- Local first: the agent uses a local model, and its Claude model takes over when the local one is busy, the job is too big for it, or it fails.
- Local only: the agent never leaves the machine. When the local model is busy, it waits for up to 10 minutes. Runs with a local-only agent only go to runners that have local models.
Leave it on The workflow's or runner's setting to follow the workflow's defaults, and then the runner's Agents and Factory threads that don't choose setting. Out of the box that's Claude only, so nothing changes until you choose.
To pick a particular local model for an agent, set Local model (for example qwen3:1.7b), or leave it on auto for the runner's default. Local models apply to agents that use the runner's own tool loop; Claude Code agents keep using Claude.
Factory threads can run on local models too: choose one in a thread's or project's model picker, or set the runner's Agents and Factory threads that don't choose to Local first for threads on Runner default. Background checks can too: give a model profile Local model only and choose it for a check.
In a workflow file:
spec:
defaults:
local: prefer # off, prefer or only
local_model: qwen3:8b # or auto
The GPU
Use the GPU on the runner's page decides when local models use the graphics card:
- When it's free (the default): the GPU is used when the model is already loaded there, or when it has enough free memory for the model and is less than half busy. Otherwise the call runs on the CPU, if the CPU is under 80% busy and has the memory. If neither has room, a Local first agent hands the call to Claude.
- Always: always the GPU.
- Never, CPU only: leave the GPU alone, for a machine you game or render on.
Local calls at once limits how many local calls run together (1 on a CPU and 2 on a GPU, unless you change it). A call over the limit counts as busy.
In a run
A run's timeline says where each model call went: Local first: qwen3:8b, then claude-sonnet-5-5 when the step starts, qwen3:8b on this runner's GPU for each local turn, and a line saying why when a call moved to Claude, such as the GPU is 93% busy. Local calls cost nothing, so a run's cost only counts the Claude calls.