Runners and agents
Runners
What a runner does, who it runs jobs for, and how a job travels from the node to your machine and back.
A runner is a machine that runs agents for a Moru node. The node keeps the repositories, the requests and the reviews; it never runs an agent itself. When you start an agent attempt or a Bake-off, the node puts jobs in a queue, and runners take them.
The runner is a separate program, moru-runner, for Linux (x86_64 and arm64) and macOS
(Apple silicon and Intel). It needs git on its PATH. A laptop, a workstation or a
server can all be runners, and one node can have any number of them.
Every runner has an owner#
A runner belongs to one person and runs only the jobs that person starts. Nobody else’s work runs on your machine or on your plan.
| Your runner | |
|---|---|
| Runs | Only the jobs you start |
| Model credential | Your agent’s login, your subscription token or an API key |
| Who adds it | You, from Runners |
| Name | Your handle in front (mira-laptop) |
A team that pays with an API key gives the key to each person’s runner. Organizations don’t own runners.
Runners registered before every runner had an owner still show up, marked as having no
owner. They get no work until a site admin gives them one with moru-node create-runner-token <name> --key <DID> --owner <user> and they restart with the
new token.
The attempt form tells you when none of your runners is online for a profile.
Open Runners from the account menu in the header. The page shows your runners and how many are online. Site admins also see other people’s runners, and runners without an owner, in tabs. A runner counts as online while it has asked for work in the last 45 seconds.
Runs as its user, with no sandbox#
The runner starts the agent (Claude Code, Codex, Gemini CLI or one of your own; see Agents) on its own machine, as the OS user that runs moru-runner, with that user’s tools, files, network and credentials. The agent runs
unattended, with its approval prompts off, and reads text other people wrote: the
request, the repository, the discussion, web pages. The runner doesn’t put a boundary around
it. Where to run a runner covers what that means and how to
choose a machine.
CI jobs#
Runners also run CI: the workflows in a repository’s .moru/workflows/, for runs that are yours, such as the revisions your agents submit and
the branches you push. A runner takes CI jobs unless it’s started with --kind naming
only implement and review. CI jobs run the same way agents do: as the runner’s user,
with no sandbox.
Outbound only#
A runner opens every connection itself. It long-polls the node for work (each poll waits up to 20 seconds), sends a heartbeat every 10 seconds while a job runs, and streams the job’s log back. The node never connects to a runner, so a runner can sit behind NAT or a firewall with no open ports.
What a runner needs to reach:
- the node, over HTTP or HTTPS;
- the model provider of each agent it runs, such as
api.anthropic.com; downloads.claude.ai, where the runner downloads Claude Code.
Agents reach whatever the machine reaches, so a repository’s package registries work as they do in your terminal.
What happens to a job#
A job is either implement (an agent writes a change) or review (an agent ranks
Bake-off candidates, or pre-reviews a change). For each job the runner:
- Leases the job. The lease carries a task token: a short-lived token for one task, for one repository, on behalf of the person who started the work.
- Fetches the repository into its object cache, so the next job in the same repository fetches only what’s new.
- Signs a claim saying how it will run the job: harness and version, model and the machine’s operating system. The node checks the claim against the runner’s registered key and refuses the job if it doesn’t match what it asked for. The agent can’t call the node until the claim is accepted.
- Makes a working copy for the job under its cache directory and starts the agent in it, in a process group of its own.
- The agent works in the working copy. When it exits, the runner commits what it left, pushes it to the task’s own scratch repo and submits a change. A reviewer files its verdict over MCP. The task token can’t push to the real repository.
- The runner reports the exit status, stops anything the job left running, removes the working copy and asks for more work.
The signed claim ends up in the change’s attestation, which the Evidence panel shows. See Provenance.
A runner runs one job at a time unless you start it with --max-jobs. With one job at
a time, the lanes of a Bake-off take turns.
When things go wrong#
- The runner goes quiet. A job whose runner stops sending heartbeats for a minute fails with “runner stopped responding”. A laptop going to sleep does this. Start another attempt from the request page.
- No runner is free. Queued jobs wait for a runner that may take them, for up to
12 hours by default (the node’s
--job-queue-ttl), then time out. - Usage limits. When an agent hits its plan’s usage limit, the job goes back to the queue until the limit resets, and that runner pauses until then (30 minutes when the agent doesn’t say). The request page shows when it will try again. After three limits, or if the reset comes after the job’s queue time runs out, the job fails.
- A lost machine. Revoke the runner on the Runners page. It stops getting work at once.
Next#
- Add a runner: install, register and start one.
- Agents: Claude Code, Codex, Gemini CLI and your own.
- Where to run a runner: what agents can reach, and how to pick a machine.
- Agent profiles: which agent and model a job runs with.