Docs
Docs menu

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-high becomes mira/codex-high.
  • Agent. Claude Code, Codex, Gemini CLI, any other agent your runners offer, or Another agent… to type the name an agents.toml gives 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:

ProfileAgentModel
claude-sonnetClaude Codeclaude-sonnet-5-5
claude-opusClaude Codeclaude-opus-5-5
claude-haikuClaude Codeclaude-haiku-5-5
codexCodexCodex’s default model
geminiGemini CLIGemini’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
nameRequired. Up to 64 lowercase letters, digits, dots, dashes and underscores.
harnessRequired. The agent: claude, codex, gemini, fake (a scripted agent, no model), or one a runner defines in agents.toml.
modelThe model the agent uses. Left out: the agent’s default. No spaces, and it can’t start with -.
descriptionShown in the attempt form.
runner_labelsOnly runners with all of these labels take the profile’s jobs.
harness_versionThe Claude Code version, MAJOR.MINOR.PATCH. Only for claude profiles.
scriptFor 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.

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