Runners and agents
Agents
The agents a runner can run (Claude Code, Codex, Gemini CLI, or your own command) and how the runner starts them.
A runner runs Claude Code, Codex, Gemini CLI, or any agent you can start from a command line. The node only names the agent a job needs, through the job’s profile. How that agent is started is up to the runner, on your machine.
What a runner offers#
By default, moru-runner run offers:
| Agent | When |
|---|---|
claude | When the runner’s user has a Claude login or key (below). The runner downloads Claude Code itself and checks it against Anthropic’s manifest. |
codex | When codex is on the runner’s PATH. |
gemini | When gemini is on the runner’s PATH. |
| your own | Every agent in agents.toml (below). |
fake | Always. The scripted agents, which call no model. |
To offer fewer, name them with --harness (repeatable):
moru-runner run --harness codex --harness gemini The runner stops at start if an agent you name isn’t installed. The Runners page lists what each runner offers, and the attempt form says when none of your runners offers a profile’s agent.
The runner looks for a Claude login when it starts: ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token), ANTHROPIC_AUTH_TOKEN or a
Bedrock, Vertex AI or Foundry setup in its environment; Claude Code’s own sign-in (in
the macOS keychain, or ~/.claude/.credentials.json on Linux); or an API key or apiKeyHelper in Claude Code’s settings. Without one it doesn’t offer Claude Code, so
jobs for Claude profiles go to a runner that can run them, and the attempt form says
when none can. It says so when it starts; sign in and start it again, or name it with --harness claude to offer it anyway.
Each agent uses whatever login it already has on the machine, as the runner’s user. If codex or gemini works in your terminal, it works in the runner. An agent that’s
installed but not signed in fails its first job with its own sign-in error, which the
job log shows.
Codex#
The runner starts codex exec with the prompt on stdin and JSON output. It turns off
Codex’s own sandbox and approval prompts, the same way Claude Code runs in bypassPermissions mode. The agent runs as the runner’s user, with no boundary around
it (see Where to run a runner). The node’s MCP server is
added for that run only, with its token taken from the environment, so your ~/.codex/config.toml stays as it is.
- Sign-in: your ChatGPT login (
codex login), orCODEX_API_KEYin the runner’s environment. Codex doesn’t useOPENAI_API_KEYfor these runs. - Usage limits: when Codex says you’ve hit your usage limit, the job goes back to the queue. Codex doesn’t say when the limit resets in a form the runner can read, so the runner waits 30 minutes before it asks for work again.
Gemini CLI#
The runner starts gemini with the prompt on stdin, auto-approval on and stream-JSON
output. It skips Gemini’s folder-trust check, since each job runs in a fresh working
copy that Gemini has never seen.
The node’s MCP server reaches Gemini through a settings file the runner writes for the
job and names in GEMINI_CLI_SYSTEM_SETTINGS_PATH. Your own ~/.gemini/settings.json and its MCP servers still apply.
- Sign-in: your Google login, or
GEMINI_API_KEY(or a Vertex AI setup) in the runner’s environment. - Usage limits: when Gemini’s quota is spent, the job goes back to the queue, and the runner waits 30 minutes, as for Codex.
Your own agents#
Define other agents in agents.toml in the runner’s state directory, <cache-dir>/.runner/agents.toml. To keep it somewhere else, pass --agents <file> or
set MORU_AGENTS. The runner reads the file when it starts.
[agents.aider]
command = ["aider", "--yes-always", "--message-file", "{prompt_file}"]
model_args = ["--model", "{model}"]
version = ["aider", "--version"]
[agents.my-reviewer]
command = ["/opt/review-bot/run", "--mcp-config", "{mcp_config}"]
kinds = ["review"] | Key | |
|---|---|
command | Required. The program and its arguments. A program without a / is looked up on PATH. |
model_args | Added to the end when the profile names a model. {model} is only allowed here. |
kinds | implement, review or both. Default ["implement"]. A reviewer must speak MCP to file its verdict. |
output | How the agent’s output reads: text (default), claude-stream-json, codex-jsonl or gemini-stream-json. |
version | A command that prints the agent’s version on its first line, for the run’s attestation. Without one: unknown. |
The agent’s name is the table’s name, here aider and my-reviewer. It’s what profiles
name in their harness. Names are lowercase letters, digits, dots, dashes and
underscores, and claude, codex, gemini and fake are taken.
Arguments go to the program as they are, not through a shell, and these placeholders are filled in:
| Placeholder | |
|---|---|
{prompt_file} | A file holding the prompt. |
{model} | The profile’s model (only in model_args). |
{mcp_url} | The node’s MCP endpoint for this job. |
{mcp_config} | A JSON file describing the node’s MCP server (see below). |
{workdir} | The job’s working copy. |
The task token has no placeholder. It stays in the environment, where other processes can’t read it from the command line.
To use another codex or gemini binary than the one on PATH, set only its binary:
[agents.codex]
binary = "/opt/codex/bin/codex" To change how Codex or Gemini is started, define an agent of your own under another name.
Claude Code always runs the release the runner downloads and checks. Choose its
version with --claude-version.
What every agent gets#
The runner starts the agent in the job’s working copy, as its own user, with its own environment plus:
| Variable | |
|---|---|
MORU_PROMPT_FILE | The prompt, which also comes on stdin. |
MORU_MODEL | The profile’s model, or empty. |
MORU_MCP_URL | The node’s MCP endpoint for this job. |
MORU_MCP_CONFIG | A JSON file with the server under mcpServers.moru, in the shape most agents read. |
MORU_TOKEN | The task token. Send it as Authorization: Bearer … to the MCP endpoint. |
TMPDIR | A temporary directory inside the job’s directory. |
MORU_MCP_CONFIG holds ${MORU_TOKEN} rather than the token, for agents that expand
variables in their config. Git in the working copy already sends the token to the node,
so the agent can fetch and push without setting anything up.
The agent doesn’t need to commit or push. When it exits, the runner commits whatever it left in the working copy and submits it as a change. An agent that commits its work itself, leaving nothing behind, names the change: its last commit’s message becomes the change’s title and description. A reviewer files its verdict over MCP before it exits.
The exit code says how it went:
| Exit code | Means |
|---|---|
0 | Done. |
75 | The agent hit a usage limit. Nothing is submitted, and the job goes back to the queue. |
| other | Failed. Work left in the working copy is still submitted, as for Claude Code. |
Pinning#
Only Claude Code can be pinned to a version (see Agent profiles). Codex, Gemini and your own agents run whatever version is installed on the runner. Their version is recorded in the run’s attestation, but a repository that requires pinned runs won’t merge their changes.