Runners and agents
Agent profiles
Agent profiles decide which agent and model a job runs with. Make your own in Settings → Agent profiles; the node's are in profiles.json.
A profile names an agent setup: which agent runs, with which model, and optionally with which Claude Code version and on which runners. When you start an attempt you pick a profile for each implementer and each reviewer, and every job carries its profile to the runner.
There are two kinds. Anyone signed in can make their own, and the node’s admins set the node’s, which everyone can pick.
Your own profiles#
Open Agent profiles from the account menu in the header. New profile asks for:
- Name. Your handle goes in front:
codex-highbecomesmira/codex-high. - Agent. Claude Code, Codex, Gemini CLI, any other agent your runners offer, or Another agent… to type the name an
agents.tomlgives it (see Agents). - Model. Left empty, the agent uses its default.
- Description, shown when you pick the profile.
- Runner labels. Only your runners with all of these labels take its jobs.
Only you see your profiles, and only you can start work with them. Their jobs run on your runners, like all your work. When none of your runners can take a profile’s jobs, the page says why, as the attempt form does.
Each profile’s agent has an identity of its own, named after the profile. Deleting a profile doesn’t change the work it did: changes and attestations keep its name.
Over the API, GET /api/v0/profiles/mine lists them, PUT /api/v0/profiles/mine/<name> adds or replaces one (harness, and optionally model, description and runner_labels), and DELETE removes it. GET /api/v0/profiles returns what you can
pick: the node’s profiles, then yours, each with owner set.
The default profiles#
A new node starts with these:
| Profile | Agent | Model |
|---|---|---|
claude-sonnet | Claude Code | claude-sonnet-5-5 |
claude-opus | Claude Code | claude-opus-5-5 |
claude-haiku | Claude Code | claude-haiku-5-5 |
codex | Codex | Codex’s default model |
gemini | Gemini CLI | Gemini’s default model |
A node set up before Codex and Gemini were supported keeps its own list. Add the two
profiles to profiles.json to offer them.
A profile’s name is also the name of its agent’s key, so each profile’s agent keeps the same DID from task to task. Changes and attestations show which agent wrote them.
In the attempt form, a profile that no online runner you can use can take right now says why: none of your runners is online, none offers the profile’s agent, or none carries the labels the profile needs. See Requests.
The node’s profiles: profiles.json#
Profiles live in profiles.json in the node’s data directory. The node writes the
defaults there on first start, and reads the file each time it needs it, so edits take
effect without a restart. There’s no page for profiles in the UI.
[
{
"name": "claude-sonnet",
"harness": "claude",
"model": "claude-sonnet-5-5",
"description": "Claude Code with Sonnet 5.5"
},
{
"name": "claude-opus-rust",
"harness": "claude",
"model": "claude-opus-5-5",
"description": "Opus on the build servers",
"runner_labels": ["build"],
"harness_version": "2.1.296"
},
{
"name": "codex",
"harness": "codex",
"description": "Codex with its default model"
},
{
"name": "aider-sonnet",
"harness": "aider",
"model": "anthropic/claude-sonnet-5-5",
"description": "Aider, defined in the runner's agents.toml"
}
] | Field | |
|---|---|
name | Required. Up to 64 lowercase letters, digits, dots, dashes and underscores. |
harness | Required. The agent: claude, codex, gemini, fake (a scripted agent, no model), or one a runner defines in agents.toml. |
model | The model the agent uses. Left out: the agent’s default. No spaces, and it can’t start with -. |
description | Shown in the attempt form. |
runner_labels | Only runners with all of these labels take the profile’s jobs. |
harness_version | The Claude Code version, MAJOR.MINOR.PATCH. Only for claude profiles. |
script | For fake profiles: which script to run. |
The node checks the file when it reads it: a malformed agent name, model or version is an error naming the profile. It doesn’t check that a runner offers the agent; the attempt form says when none of yours does.
Scripted agents#
moru-node serve --scripted-profiles (or MORU_SCRIPTED_PROFILES=true) adds scripted
profiles such as fake-tidy, fake-thorough and fake-reviewer to the file. They go
through the same git and MCP steps as a real agent without calling a model, which is
useful for trying Moru out or testing a setup. Every runner can run them, with or
without a model credential. The flag adds only missing ones and never changes a profile
you’ve edited.
Runner labels#
Labels keep a profile’s jobs on particular runners, such as your build server with more memory rather than your laptop. Give runners labels when you mint their token on the node:
moru-node --data /var/lib/moru create-runner-token mira-build-1 --key did:key:z6Mk… --owner mira --label build Then list the labels in the profile’s runner_labels. A runner without every listed
label never leases that profile’s jobs.
Pin the Claude Code version#
Runners download Claude Code from Anthropic, check it against Anthropic’s release
manifest, and run that binary rather than any claude on the machine’s PATH. By default they use the latest
release, or the version a runner was started with (--claude-version, or MORU_CLAUDE_VERSION).
To fix the version for every run, pin it on the claude profiles:
moru-node --data /var/lib/moru pin-harness 2.1.296 Add --profile <name> (repeatable) to pin only some profiles. Each runner downloads the
pinned version the first time it needs it and keeps it in its cache dir.
Require pinned runs#
The change’s Evidence panel says when a run’s Claude Code version wasn’t pinned. To go further, a repository can refuse to merge agents’ changes from runs that didn’t use a pinned Claude Code version:
moru-node --data /var/lib/moru repo-policy acme/timetable --require-pinned true Without --require-pinned, the command shows the repository’s current setting. See Provenance for what the Evidence panel checks.