Runners
Reverses the direction: the board sends cards to an agent on a machine of yours when something happens, such as a card arriving in a list. The agent works the card and reports back.
Use it when you want work to start without anyone opening a session, such as a list that agents empty on their own, or a queue several machines share.
How they work
With the other options, you start an agent and it reads the board. A runner works the other way round. An automation rule queues a job for a pool, for example whenever a card arrives in a list. A runner in that pool, on a machine of yours, takes the job, runs the agent on the card, and reports how it went.
Runners pull: they connect out to ask for work, and the server never connects to them, so there are no ports to open or tunnels to set up. The server sends only the card and a prompt. What actually runs is decided by the runner's own config on your machine, and a kind of job it doesn't define is refused. A runner's token can only take and report on its own pool's jobs.
On a board with profiles on, a claimed job also carries the card's profile: one word for what kind of change it is, security, schema, feature, fix,
docs
or spike. It is the card's own, else the one its paths and tags infer:
a security path makes it security, a migration schema, a
bug
tag fix, only docs paths docs, a spike
tag spike, anything else feature. It is profile
in claim_job's answer and the session claim's job, profile:
in slipdock claim-job, and SLIPDOCK_PROFILE
in a runner's job, where the runner's config can pick a model for it
(MODEL_feature). The profile decides how the work is checked: a docs
card gets no verifier, a schema
or security
one a defect review and, on a board that ships by pull request, waits by default for a
person before it merges, and a spike
merges nothing. A fix, feature, schema
or security
card's verifier mutates the change: 3 to 5 of its most consequential lines and every
guard or branch it adds, each named with its line, and it checks each claim in the
builder's evidence rather than carry it. An agent may raise a card's profile once work has started, never lower
it, and the change it completes with can raise it too (slipdock done 12 --diff-base origin/main). With profiles off, no profile is sent.
What happens to the card after that, from the claim through building, CI and a second agent's check to the deploy, and where it waits for you: How work flows .
Set one up
On the board, open Automations → Connect a runner. It asks where the work should happen and gives you exactly what to paste:
| Where | What it is | Cost while idle |
|---|---|---|
| A machine with the daemon |
slipdock-runner init
with a one-time enrolment key made for the board, then its runners set on the machine's page
|
Nothing |
| Claude Code | A /loop that takes jobs from the pool's queue |
A Claude turn per check |
| Claude, scheduled | A Claude Desktop or cloud routine with the Slipdock connector | A Claude turn per run |
| ChatGPT | A chat or scheduled task that claims one job and works it in the conversation | A ChatGPT turn per check |
The shell and PowerShell runners the daemon replaced were retired: this server no longer serves them. One still running keeps working with its token until it is moved: Move to a machine on it in the Runners panel gives the steps.
A machine running the runner daemon enrols once: slipdock-runner init
shows a code and the machine's fingerprint, and you approve it under Account → Machines, checking the hostname, system and fingerprint and
choosing the boards it may serve, from those you own or can write to. It gets a machine key of its own, which is not an API
token, and revoking the machine there stops the key at once. For a machine with nobody
at its screen, make a one-time enrolment key on the same page: the name you give it is
the name the machine enrols under, or its hostname without one.
The daemon looks after its own connection to this server, so a laptop that sleeps or changes networks runs jobs as well as a machine that is always on. It pings a connection that has been quiet for 15 seconds and replaces it if no answer comes within 10, never retries a failed request on the connection it failed on, and when the clock jumps (the machine woke from sleep) drops its connections and asks for work again at once. Meanwhile the machine shows offline after about 4½ minutes unheard from, and a job it held goes back in the queue once its 90-second lease runs out. If no other runner has taken that job when the machine wakes, its runner takes it back with its next heartbeat and the agent carries on where it was; if one has, the woken runner stops its copy.
When the agent can't run at all (its account has hit a usage limit, or it can't sign in) the daemon reads that as the machine's trouble, not the card's: the agent's limit message (You've hit your weekly limit · resets Nov 15, 6pm), or an agent that exits non-zero within a minute before a single tool call. The job goes back in the queue as though it had never been claimed, and its card is left as it was: no failure, no handoff, no blocked flag. Every runner on the machine with that agent then takes no job until the reset the message states (an hour when it states none), or, after a quick exit, for a minute, doubling to 30, until a job runs normally; one already waiting in its claim gives the job it is handed back unrun. The board gets one warning alert for the machine (Runners on build-box stopped: …), not one a job. Restart the daemon to try sooner, once the account is mended.
Each machine has a page of its own, opened from that list: whether it is online, the
ceiling and executors it reported, its runners and what each is working on, and the
log of settings it accepted or refused. There you add, change, pause and remove its
runners, rename the machine (its hostname stays), add or remove the boards it serves
without enrolling it again, ask it to update now, and revoke it. A board added there
is marked not in the ceiling
until someone at the machine runs slipdock-runner boards add
with its number; a board with runners on
the machine comes off once they are removed.
A setting outside the machine's ceiling
is marked with the limit; if you save it anyway the machine refuses it, and the page
shows the refusal with its reason and the limit. People who share a board with the
machine see its page but can't change it.
Probe
a runner from that page, or with slipdock machine probe, to check it is ready to work without a shell on
the machine. The runner checks its directory is a git repository with an origin, its
agent answers --version, gh
is signed in, the slipdock skills
and CLI are this server's, and its executor runs a command, then runs its probe hook
if it has one. The page shows the probe green with when it passed, or red with its
log. A probe is a job with no card, sent only to that runner.
After a deploy there is nothing to do on the machine: before each agent job (not a
merge or a probe) the daemon puts this server's slipdock skills in place and, when
/cli/SHA256SUMS
differs from its slipdock
CLI, fetches this server's CLI, checks its SHA-256 and puts it in the daemon's own
folder, first on the job's PATH, never over a copy installed elsewhere unless the
machine's local.json
names it as cli. The CLI is installed only when its signature verifies
against the release key built into the daemon: the release job signs each v*
tag's, and a server built from source, or a deploy it didn't sign, serves none, so the
machine keeps its own CLI unless local.json
sets cli_checksum_only. Until the next tag is deployed, its runner shows
CLI unsigned on server
rather than old CLI: the cause is the server's, not the machine's. A failed fetch or a wrong sum keeps the CLI it had, and
the job runs. The skills are installed the same way, only when their archive's
signature verifies against that key, and a server that serves none leaves the
installed skills in place unless local.json
sets skills_unsigned; its runner then shows skills unsigned on server
rather than skills drifted
until the next tag is deployed, with no alert. The runner reports the current CLI at its next claim, and its probe goes
green. no_cli_update
(and no_skills_update) in local.json
turns it off.
On a board with batched releases the daemon also fires the release, as it merges: a
release
job has no agent and no card. It runs
gh workflow run <workflow> --ref <branch>
itself and logs the run it started. Any other release command a board sets runs only
when the machine's local.json
lists it, word for word, under release_commands; the daemon refuses the
rest, since it never runs what the server sends. no_release: true
there turns the kind off. A card on such a board is done when it merges: an agent
neither waits for its release nor fires one, Release now
is how a person ships, and a card's Not shipped
line counts from its release, not its merge.
Set up this machine with Claude, on the machine's page and at the end of
slipdock-runner init
(or slipdock-runner setup
later), starts
Claude Code on the machine, as the account its jobs run as, with a prompt that reads each
board's machine-setup page (the handbook's Testing & tooling, Local setup). It checks
what the machine has, installs what's missing, proves it by cloning the repository and
running its suite, and corrects the page where it was wrong, so the next machine is set up
from the page alone.
What the server can and cannot do
A machine with the runner daemon takes data from this server, never a command. This
is the trust contract: the same text is on each machine's page, and on the machine
slipdock-runner show
prints it after that machine's own limits.
A Slipdock server queues work for the machines that run its runners. This
is what it can and cannot make such a machine do, and what none of this
protects you from. Read it before you install the runner daemon on a
machine. On the machine, slipdock-runner show prints it with that
machine's own limits.
What the server can do
- Queue jobs for the pools this machine's runners joined. Each job comes with a prompt: the card, and what the board's members wrote for the agent to do.
- Set each runner's settings: its pool, agent, working directory, permission mode, timeout, model, worktree, verbosity, standing instructions, executor, and the names of its hooks. These are data, not code, and they apply only inside the machine's ceiling. A setting outside the ceiling is refused on the machine, and the runner keeps the settings it last accepted.
- Start a release. On a board that releases in batches, a
releasejob has a runner here rungh workflow run <workflow> --ref <branch>in its repository, as the accountghis signed in as. The board names the workflow file and the branch (by default the repository's default branch), and the daemon checks both as plain names before it uses them.no_release: trueinlocal.jsonturns this off. - Name a newer version of the daemon.
What the server cannot do
- Run a command on this machine. The daemon never runs anything the
server sends. The agents, custom commands and hooks it can run are
defined in files on the machine, and the server can only pick one of
them by name. A board's release command is no exception: one that isn't
the
gh workflow runabove runs only whenlocal.jsonlists it, word for word, underrelease_commands; any other is refused and nothing runs. - Change a hook or a command, or add one.
- Change the ceiling. It is a file on the machine (
ceiling.json) that the server never reads or writes; only someone at the machine edits it. - Set a working directory outside the ceiling's roots, an agent it doesn't list, a permission mode above its highest, a timeout above its longest, a board it doesn't serve, or an executor it doesn't allow.
- Read files on this machine. What reaches the server is what the daemon sends: each job's log and the agent's transcript, which hold whatever the agent read or printed while it worked.
- Install an update that isn't signed with the project's release key, which is built into the daemon. Whoever serves an update, the daemon checks the signature and refuses one that doesn't verify.
- Give the agent a
slipdockCLI the project didn't sign. Before each agent job the daemon puts the server's CLI in its own folder, first on the job's PATH (or over the onelocal.jsonnames ascli), only when its signature verifies against the same release key. A server that serves no signature (one built from source, or a deploy the release job didn't sign) leaves the machine's own CLI in place, unlesslocal.jsonsetscli_checksum_only. - Give the agent slipdock skills the project didn't sign. Before each
agent job the daemon puts the server's slipdock skills in place, and
they are instructions the agent follows, so it installs them only when
the archive's signature verifies against the same release key. A server
that serves no signature leaves the installed skills in place, unless
local.jsonsetsskills_unsigned. - Raise a job to the owner tier on its own word, once owner keys are
pinned. With
owner_keysin the ceiling (pinned by a person at the machine withslipdock-runner trust-owner), a job the server says isownertier runs asowneronly when its card's title, description and bar carry a signature by one of those passkeys. The daemon checks it itself: the challenge is its own SHA-256 of the text, with the server's origin, the card and when it was signed; the origin and relying party are the pinned key's; the owner was present and verified; and the signature is no older than the ceiling allows. Any other job runs asmemberat most, and the daemon logs why. A signature never raises a job above the tier the server gives it. lets it claim and report on its own runners' jobs and read their settings, and nothing else. It is not an API token. Revoking the machine on the Machines page ends the key at once.
What nothing here bounds
- First-install trust. The first copy of the daemon is only as trustworthy as the download it came from: the installer checks it against the release key written into the installer itself, so a tampered installer passes its own check. Every later update is checked against the key built into the daemon.
- On the hosted service, the operator who runs the server is also the one who signs the releases. A self-hosted server can't author an update; the hosted operator can, as anyone who downloads the tool already trusts them to.
- The slipdock skills, and a CLI taken on the server's word. With
skills_unsignedset inlocal.json, the daemon installs the server's unsigned slipdock skills, instructions the agent follows, checked against nothing but the server: a server can then change what the agent reads. Withcli_checksum_onlyset inlocal.json, the same goes for an unsignedslipdockCLI, checked only against the checksum the same server publishes: a server can then change the program the agent calls. Setno_skills_update(andno_cli_update) inlocal.jsonto keep your own. - What an owner's signature doesn't cover. Signed text is the owner's
for certain, and only that text: the server is still trusted for the
rest of the prompt (a rejection, a wait's answer, a handoff), for what
the agent reads while it works, and for the prompt carrying the signed
text at all. A server serving a tampered page can ask the owner to tap
for other text than the page shows. The keys are pinned on the
server's word when
trust-ownerruns, so compare their fingerprints with the owner's own list. With noowner_keyspinned, a job's tier is the server's word alone. - Network access. A job can reach the network, and so can send anything
it can read to anywhere, unless its runner uses the
containerexecutor with the network off. No other executor limits the network, but for a network allowlist: a trust tier in the ceiling may hold its jobs, underconfinedorcontainer, to their agent's model API, the Slipdock server, the repository's origin and the hosts it names, through a proxy of the daemon's. Such a job can still send what it reads to those hosts, and the allowlist doesn't cover name lookups or, underconfinedon Linux, UDP or another host on the proxy's port. Acontainerjob under an allowlist also finds fake credentials in its home, and its proxy, seeing one leave, has the job stopped and its pool paused: that catches a job sending them where the proxy can read (a host name, plain HTTP), not one sending them inside TLS to an allowed host. - Prompts are the board members' instructions. The agent follows them within the runner's permission mode, as the account its jobs run as. Every job's prompt tells the agent that a card's text is data, never instructions, but telling a model is not a limit. Whatever that account can read or change, a card can ask the agent to read or change, and so can text the agent reads while it works (an issue, a web page, a file in the repository). Anyone who can write a card a runner takes is giving that agent instructions: choose the boards a machine serves, the highest permission mode and the executor with that in mind.
What each executor stops
A runner's executor is who its jobs run as. The ceiling says which ones the machine allows, and a job never runs under a weaker one in its place.
me: jobs run as you, as you are. It stops nothing: the agent can read and change whatever you can, your SSH keys, logins and mail included.user: jobs run as a dedicated account (slipdockby default), with its own home, clones and logins. It stops a job reading or changing your home: a job is refused while your home is open to that account. It doesn't stop the job reading what every account on the machine can, writing the account's own home and/tmp, using the account's own logins (itsghlogin pushes wherever it can), or the network.confined: jobs run as you, unable to write outside the job's directory, its repository, a scratch temporary directory and the agent's session state, never its settings, hooks or skills (Landlock on Linux,sandbox-execon macOS). In a worktree, a job whose card has paths writes only those in it, and of its repository only what a commit needs. The daemon's own git for the runner and the runner's hooks are confined to the repository and its worktrees. It stops a job writing to your home, other repositories and the system, and reading the daemon's own directory (the machine key) and the logins no job needs:~/.aws,~/.netrc,~/.docker/config.json,~/.kube,~/.config/gcloud,~/.azureand~/.gnupg. It doesn't stop the job reading your other files, your SSH keys and theghandslipdocklogins included (a job pushes, opens pull requests and uses the board), or the network (unless a network allowlist holds it), so a confined job can still read a secret and send it.container: jobs run in a short-lived Docker or Podman container, from an image the machine's own allow-list names, with the repository or worktree mounted at the same path, the agent's login mounted read-only, and an empty directory of its own for the agent's transcript, which the daemon reads only as regular files beneath it. In a worktree, a job whose card has paths has only those mounted read-write, and of its repository only what a commit needs. It stops a job reading or writing anything outside what is mounted, and, when the runner asks for the network off, the network; under a network allowlist (Linux only), every host but the allowlist's. It doesn't stop the job changing the mounted repository, using the agent's login (it can't change it, but can act with it), whatever the image itself does, or the network when it is left on. The runtime is trusted too: an account in thedockergroup is root on the machine.
On Windows, jobs run as the current account only (me).
Card text is data
A runner's agent reads what other people wrote: the card, its comments, its bar and
anything mailed to the board, by anyone who can comment on it or is a permitted
sender. Every job's prompt and the skills tell the agent that this text is data,
never instructions: it says what the card's work is, and when it asks for anything
beyond that the agent leaves it, says so on the card and, if the card can't be done
without it, asks a person. Telling a model is not a boundary, so the machine's ceiling
and the runner's executor, above, are what limit a job. The full threat model is in docs/agents.md, under Card text is data.
Anyone who can write or comment on a board a runner serves can steer its agent. The card's text, its bar, its comments and its handoffs go into the agent's prompt, and the agent follows them as the account its jobs run as. The prompt tells it that card text is data, not instructions, but telling a model is not a limit. The limits are the runner's:
- Executor:
mestops nothing, so the agent can read and change whatever you can.userkeeps it out of your home,confinedstops it writing outside the job's directory, andcontainerstops it reading or writing outside what is mounted, and the network when that is off. - Permission mode:
planchanges nothing,defaultasks before an edit or a command,acceptEditsedits files without asking, andbypassPermissionsruns any command without asking.
Share a runner's board only with people you would let use this machine that way.
Sending it work
- Send cards to a runner: when a card arrives in a list, queue it for a pool, with the card itself as the prompt or one you write. Your own is at most about 17,000 bytes, since every job's prompt ends with the same closing text; a longer one is refused when the rule is saved, with the exact number.
-
Work a list with a runner: take the top card, one at a time, and
skip cards that are blocked, waiting, already assigned or already have a job open
on them, so two such rules for two pools can share one list. A rule whose runners have all gone offline sends nothing, and
gives back a card it sent that no runner has taken yet, so a runner that is online
picks it up. This is how a runner
takes over from a
/loopworking the To Do list. -
A Claude or ChatGPT session can also take jobs from the same queue itself, with
claim_jobover MCP orslipdock claim-job, so a loop and a machine's runner never work the same card. -
A pool's jobs are the board owner's. Somebody else takes them, from a session or their
own machine, only once the owner grants them that pool under
Who takes each pool's jobs
on the Automations panel (or
slipdock pool-grant), and while they can write the board.
Good to know
-
Jobs run with nobody watching. Every prompt says so, and tells the agent to choose
from what's on the card, or to open a wait
saying what it needs and stop. The job is parked, the card goes back on top of its list
so the next one runs, and answering the wait (on the card, in My work's Waiting on you, or
slipdock answer) sends the card to the rule again with the answer at the top of the prompt, for any free runner of the pool: it isn't held for the runner that asked. -
A job that ends with its card still open leaves its summary as the card's handoff, the note the next person or agent reads first, unless the agent
left one itself with
leave_handofforslipdock handoff. - Give the runner the project's folder as its working directory. Claude Code only loads a project's own commands and settings from the folder it starts in.
-
Pause
in the Runners panel holds the whole board tree, or one pool,
with a reason: nothing is taken and no list sends a card until you resume it. Agents
can pause (
manage_automation,slipdock pause) but only a person can resume, and an agent that seespausedtakes nothing and stops. Held jobs say why: paused, WIP full (with WIP limits hold automated work on, on the board's Agentic Building page), waiting on a card in progress, or no runner online. -
State line and age.
A card with a job or a wait on it says so in one
line (
statein REST,list_cardsandslipdock cards), withdriver(agent or human) on trees with runner rules and itsagein the list.stuckmarks a card past its list's usual stay (never an epic with open subcards, whose stay is theirs); filter on it withstuck: trueor--stuck, and ondriver. -
Where a card came from.
Every card records its
origin(a person, the sweep, findings, the health monitor, the overseer, verification, a rule, an import, or an agent with its job). Filter on it with--originororigin; inside a job, name the generator you run withslipdock add … --origin sweep. Nobody can claim to be a person. -
The loop on a card.
While a runner's job holds a card (claimed or running), its Assignees show the
runner and the job's kind, build or verify, linked to the job:
loopin REST,get_cardandlist_cards, aLoop:line inslipdock card. It goes when the job ends. It is not an assignee: a runner's agent signs in with a person's token, so it leaves the assignees alone, and every assignee filter still means people. -
Timeline.
How long a card sat in each list, who moved it, and its waits
and jobs:
get_cardwithtimeline: true,GET /api/cards/:id/timelineorslipdock timeline <id>. - With Work a list with a runner, a card its job leaves in progress goes back to the top of the list for another try, then gets flagged as blocked.
- ChatGPT has no shell or repository, so give it its own pool of cards it can finish in conversation, such as writing, research or planning.