Docs
Docs menu

Add a runner

Install, register and start moru-runner in one command, or step by step, and keep it running.

The Add a runner page gives you one command that installs the runner, registers it with a one-time code and starts it, filled in for your node. Step by step on the same page splits it into its three parts, install, register and run, which this page goes through.

Before you start#

  • Linux (x86_64 or arm64) or macOS.
  • git on your PATH. moru-runner register checks for it.
  • For real agents, an agent and its model credential: Claude Code with a Claude subscription or an Anthropic API key, or Codex, Gemini CLI or your own agent with its own sign-in.
  • A machine or user account you’re happy for an agent to use. The runner runs agents as its own user, with no sandbox. See Where to run a runner.

In one command#

Run the page’s command on the machine, as the user the runner will run as:

curl -fsSL https://moru.example.com/install-runner.sh | sh -s -- --code mrr_… --name laptop --run

The install script takes these options after sh -s --:

Option
--code CODERegister with this one-time code once installed. Needs --name.
--name NAMEThe name for this machine.
--node URLThe node to register with. Default: the node that served the script.
--runStart the runner once registered, in the current directory, where register keeps the cache dir.

A node built from source has no runner downloads, so its page uses the script from moruforge.com and adds --node with your node’s address. The page shows when the runner comes online. The sections below are the same steps, one at a time, with the options the one command leaves at their defaults.

1. Install#

Open Runners from the account menu, then Add a runner.

Under Step by step, the first step is the install command. A node running the released image serves the runner of its own version:

curl -fsSL https://moru.example.com/install-runner.sh | sh

A node built from source has no runner downloads, and the page shows this command instead:

curl -fsSL https://moruforge.com/install-runner.sh | sh

The script picks the build for your OS and CPU and unpacks moru-runner into ~/.local/bin. Set MORU_RUNNER_BIN_DIR to install somewhere else. If the directory isn’t on your PATH, the script says so.

2. Register#

On the same page, choose a Name for this machine. The node puts your handle in front of the name: laptop becomes mira-laptop. The page then shows a register command with a one-time code:

moru-runner register --node https://moru.example.com --code mrr_… --name laptop

The code works once and expires after 15 minutes. New code gives you another. You hold at most five unused codes: a new one retires your oldest.

Run it as the user the runner will run as. Before it contacts the node, register checks that git is installed. Then it creates the runner’s signing key and saves its token in <cache-dir>/.runner/token.json. The cache dir defaults to ./runner-cache in the directory you run the command from. Pass --cache-dir with an absolute path to keep it somewhere fixed, and pass the same --cache-dir to run:

moru-runner register --node https://moru.example.com --code mrr_… --name laptop \
  --cache-dir ~/.moru-runner

The token lasts 30 days and the runner renews it while it runs. One cache dir holds one runner. To register a different runner from a dir that already has one, add --replace; the old runner can’t start from that dir afterwards.

3. Start it#

Start the runner as the same user:

moru-runner run

Agents use that user’s logins, so if claude, codex or gemini already works for you on this machine, there’s nothing more to set. The runner offers Codex and Gemini CLI when they’re on its PATH, and Claude Code when it finds a Claude login or key; see Agents.

Otherwise, give the runner a credential in its environment. For Claude Code with a Claude subscription, get a token from Claude Code’s own sign-in flow:

claude setup-token
CLAUDE_CODE_OAUTH_TOKEN=… moru-runner run

With an API key:

ANTHROPIC_API_KEY=… moru-runner run

Codex takes CODEX_API_KEY and Gemini CLI GEMINI_API_KEY the same way.

Add --cache-dir if you registered with one. The runner waits for work and shows up as Online on the Runners page.

The credential stays on your machine. The runner removes it from every log line it sends to the node. Agents run as the same user, so they can read it.

Your own Claude subscription#

Every runner belongs to a person and runs only the jobs that person starts. Anthropic’s terms let you use your own subscription with unmodified Claude Code; they don’t allow a platform to route other people’s work through it. Since no runner takes anyone else’s jobs, your subscription only pays for your own work.

Things to know when your laptop is the runner:

  • One job at a time is the default. A Bake-off’s lanes take turns. Start the runner with --max-jobs 2 (or more) to run lanes side by side, at the cost of using your plan faster.
  • Reviews on your own runner. Your runners review every candidate of a Bake-off, the ones they wrote included.
  • Usage limits. When a job hits your plan’s limit, it goes back to the queue until the limit resets, and the runner pauses until then.
  • Sleep. A job fails if its runner goes quiet for a minute. Queued jobs wait for your runner to come back, up to the node’s queue time (12 hours by default).

From the node’s shell#

An operator can also register a runner without the UI. On the runner, print its key:

moru-runner key --cache-dir /var/lib/moru-runner

On the node, mint a token for that key, naming the person the runner works for:

moru-node --data /var/lib/moru create-runner-token mira-server --key did:key:z6Mk… --owner mira

Then start the runner with the token in the environment, not on the command line:

MORU_RUNNER_TOKEN=… moru-runner run --node https://moru.example.com --cache-dir /var/lib/moru-runner

create-runner-token takes:

Flag
--owner <handle>The person the runner works for. Required.
--label <label>A pool the runner belongs to (repeatable). Profiles can require labels; see Agent profiles.
--ttl <duration>How long the token lasts. Default 90d.

A token minted this way doesn’t renew itself: mint a new one before it expires. Labels are set only this way, also for a runner registered from the UI.

Options for run#

The ones you’re most likely to need:

FlagDefault
--cache-dir <dir>./runner-cacheWhere the runner keeps its key, token and object cache.
--max-jobs <n>1Jobs to run at once.
--kind <kind>bothTake only implement or only review jobs (repeatable).
--harness <agent>all it hasOffer only these agents (repeatable). See Agents.
--claude-version <x.y.z>latestClaude Code version for profiles that don’t pin one. Also MORU_CLAUDE_VERSION.

moru-runner run --help lists the rest, and moru-runner describes every command.

Keep it running#

moru-runner run stays in the foreground until you stop it. Ctrl-C (or SIGTERM) stops it gracefully: it takes no new jobs, finishes the ones it’s running, removes their working copies and exits. A second signal cancels the running jobs and still cleans up. A third exits at once.

When a runner of yours is offline, the Runners page shows the command that starts it again, with its cache dir and job count filled in.

On a Linux server, run it under systemd, as a user of its own (see Where to run a runner). Put the credential in a file only root can read:

# /etc/moru-runner.env (mode 0600)
ANTHROPIC_API_KEY=sk-ant-…
# /etc/systemd/system/moru-runner.service
[Unit]
Description=Moru runner
After=network-online.target
Wants=network-online.target

[Service]
User=moru-runner
EnvironmentFile=/etc/moru-runner.env
ExecStart=/home/moru-runner/.local/bin/moru-runner run --cache-dir /var/lib/moru-runner --max-jobs 2
Restart=on-failure
# systemd sends SIGTERM, and the runner finishes its jobs first. Give it time.
TimeoutStopSec=30min

[Install]
WantedBy=multi-user.target

Register it first as the same user, with the same --cache-dir. Install the toolchains your repositories need where that user can run them.

Revoke or delete a runner#

On Runners, Revoke stops a runner getting work at once: use it when a machine is lost. A revoked runner keeps its name. Delete then removes it and frees the name, so a new machine can be registered under it. From the node’s shell, moru-node revoke-runner <name> revokes any runner and moru-node list-runners lists them all.

To bring a revoked runner back, add it again with a new code.

Command menu
Search for a page, repository, change or request, or run a command