spawn MCP tool

Creates a new agent. Configures the agent’s repo(s), branch, model, session mode, idle behavior, and task checklist, then launches it on an ephemeral VM. If the agent is already running, returns an error — use queue_add to send a follow-up instead. Equivalent to murmur spawn in the CLI.

Parameters

Name	Type	Required	Description
`slug`	string	yes	Agent task slug (e.g. `fix-auth-bug`). When `flight` is set, defaults to `flight-<name>`.
`description`	string	yes (autonomous)	Task description or follow-up message. Required for autonomous mode unless `flight` is set.
`workspace`	string	yes (new spawns)	Workspace name. The server resolves repos and environment from the workspace definition.
`branch`	string	no	Working branch for every repo in this spawn. Per-repo overrides in `repos[].branch` take precedence.
`purpose`	string	no	One-sentence human-readable summary of the agent’s goal (e.g. “Add pagination to the users API”). Displayed in the dashboard. Max 240 characters.
`model`	string	no	Model override (e.g. `claude-opus-4-8`).
`agent`	string	no	Claude Code agent persona (e.g. `programmer`, `architect`).
`service_profile`	string	no	Spawn under this service profile — borrowing a non-owned profile, which requires the `service-profile.assume` permission. Use `spawn_profiles` to discover which profiles you can borrow.
`backend`	string	no	Code agent backend: `claude` (default) or `codex`.
`reasoning_effort`	string	no	Reasoning effort level. Claude: `low`, `medium`, `high`, `xhigh`, `max`. Codex: `low`, `medium`, `high`, `xhigh`. Empty = model default.
`reasoning_summary`	string	no	Codex reasoning summary: `auto`, `concise`, `detailed`, `none`. Only valid for `backend=codex`.
`verbosity`	string	no	Codex verbosity: `low`, `medium`, `high`. Only valid for `backend=codex`.
`service_tier`	string	no	Codex service tier: `standard` (default), `fast`, `flex`. Only valid for `backend=codex`.
`repos`	object[]	no	Repos to clone with optional branch overrides. Each entry must have `clone_url`. See Repo object.
`session_mode`	string	no	`autonomous` (default), `interactive`, or `streaming`.
`completion_check`	string	no	`none` (default) or `assessor` (run completion assessor up to 3x before idling).
`on_idle`	string	no	Idle behavior: `sleep` (default), `terminate`, or `keep_alive`.
`idle_timeout`	string	no	How long the agent waits idle before acting on `on_idle`, as a positive Go duration (e.g. `45m`). Empty uses the platform default (`20m`).
`dequeue_strategy`	string	no	Follow-up dequeue strategy: `auto` (default — up to five follow-ups of one kind per turn; manual follow-ups and auto-generated events never share a turn), `all` (drain all into one batch), `one` (one per turn), or `five` (up to five per turn).
`suppress_events`	array of strings	no	GitHub event classes the agent ignores (never woken by): `ci` (CI results), `pr_comments` (PR comments and reviews). Omit to inherit the `suppress_events` config default; pass an empty list to force full subscription over it. Suppressed events are still recorded on the agent’s timeline.
`resurrect`	boolean	no	Resume a completed/killed agent on the same branch with its full conversation history. Requires the same slug. Default: `false`.
`force_new`	boolean	no	Start fresh even if a prior session exists. Default: `false`.
`fork_from`	string	no	Branch off another agent’s conversation into a new independent agent. Use a new slug — the fork gets the parent’s history but diverges from that point.
`tasks`	string[]	no	Checklist items the agent must complete.
`tags`	string[]	no	Tags to attach for dashboard grouping and filtering. Each must be a DNS-label slug (`[a-z0-9][a-z0-9-]{0,62}`); max 8. A name that matches no existing tag is created with a default color.
`append_system_prompt`	string	no	Text appended to the agent’s system prompt.
`out`	string	no	Expected output artifact. Short keywords are expanded: `pr` (open a pull request), `push` (push changes, no PR), `respond` (just respond, no code changes). Freeform text is passed through verbatim.
`flight`	string	no	Flight file path relative to `.murmur/flights/` (e.g. `deploy.md`). When set, reads and executes the flight via a pilot agent.
`flight_inputs`	object	no	Context inputs for the flight, injected into the pilot prompt (e.g. `{"repo": "org/repo", "number": "42"}`). Only used when `flight` is set.
`each`	string	no	Fanout: path to a file containing one item per line. Spawns one agent per line. `slug` and `description` must contain `{}` which is replaced with each item.
`env`	string[]	no	Environment variables forwarded to the agent as secrets, the `murmur spawn -e` equivalent. `"FOO=bar"` sets a value explicitly; a bare `"FOO"` forwards it from the calling client’s own environment (local stdio servers only — the hosted server has no caller environment to read and rejects the bare form). Names must match `[A-Z][A-Z0-9_]*` and cannot be a credential name — `GH_TOKEN`, anything starting with `MURMUR_`, the OAuth mounts, `CLAUDE_TOKEN`, or `SIGNING_KEY` — since those belong to the identity the agent runs as. Top-level spawns only — a child agent inherits its parent’s secrets, so a child request naming one is rejected rather than ignored. Agents running under a service profile receive them too, alongside the profile’s own credentials; only `GH_TOKEN` is left to the profile, whose minted GitHub token stays the agent’s git credential.

Repo object

Field	Type	Required	Description
`clone_url`	string	yes	Canonical clone URL (e.g. `https://github.com/org/repo`).
`base_branch`	string	no	Base branch to branch from (e.g. `main`). Resolved from tenant config or workspace default if omitted.
`branch`	string	no	Working branch for this repo. Overrides the top-level `branch`.

Response

Returns the slug of the spawned agent.

Field	Type	Description
`slug`	string	The slug of the spawned agent.

When each is used, returns a list of spawned slugs instead:

Field	Type	Description
`slugs`	string[]	Slugs of all spawned agents.
`count`	integer	Number of agents spawned.

Examples

Basic autonomous agent

{
  "slug": "fix-auth-bug",
  "description": "Fix the authentication bypass in the login handler",
  "workspace": "backend",
  "out": "pr"
}

Response:

{
  "slug": "fix-auth-bug"
}

With model and persona

{
  "slug": "api-refactor",
  "description": "Refactor the users API to support pagination",
  "workspace": "backend",
  "model": "claude-opus-4-8",
  "agent": "architect",
  "on_idle": "terminate",
  "out": "pr"
}

Multi-repo spawn with branch overrides

{
  "slug": "cross-repo-fix",
  "description": "Update the shared proto and regenerate clients",
  "workspace": "platform",
  "branch": "proto-update",
  "repos": [
    {"clone_url": "https://github.com/org/protos", "branch": "update-user-proto"},
    {"clone_url": "https://github.com/org/api-server"}
  ],
  "out": "pr"
}

Resume a dead agent

{
  "slug": "fix-auth-bug",
  "resurrect": true,
  "description": "Continue fixing the auth bug — tests are still failing",
  "workspace": "backend"
}

Fork from another agent

{
  "slug": "fix-auth-v2",
  "fork_from": "fix-auth-bug",
  "description": "Try a different approach to the auth fix",
  "workspace": "backend",
  "out": "pr"
}

Flight execution

{
  "slug": "deploy-v2",
  "flight": "deploy.md",
  "flight_inputs": {"version": "2.1.0"},
  "workspace": "platform"
}

Forward environment variables

{
  "slug": "run-migrations",
  "description": "Run the pending billing migrations and report the result",
  "workspace": "backend",
  "env": ["DATABASE_URL=postgres://localhost/mydb", "API_KEY"],
  "out": "respond"
}

DATABASE_URL is set explicitly. API_KEY uses the bare form, which a local stdio server reads from its own environment, so the value never enters the conversation. The server encrypts both before they reach the agent’s VM, where the agent reads them as environment variables.

The bare form works only against a local stdio MCP server, which runs as you. The hosted server rejects it — the only environment it could read is the platform’s own — so pass every variable as NAME=value there.

Fanout

{
  "slug": "lint-{}",
  "description": "Run linter on {}",
  "each": "/tmp/repos.txt",
  "workspace": "platform",
  "out": "pr"
}

Response:

{
  "slugs": ["lint-api-server", "lint-web-client", "lint-shared"],
  "count": 3
}

Errors

Code	Meaning	What to do
`ALREADY_EXISTS`	An agent with that slug is already running.	Use `queue_add` to send a follow-up, or pass `force_new: true` to start fresh.
`INVALID_ARGUMENT`	Missing required field, invalid enum value, or `resurrect` and `force_new` both set.	Check the error message and fix the input.
`NOT_FOUND`	Workspace, flight, or fork source not found.	Verify the workspace name, flight path, or fork_from slug.
`UNAUTHENTICATED`	Identity token is missing or expired.	Check credentials.

murmur spawn — equivalent CLI command
Agents — concept overview
status — check agent state
ls — list running agents
kill — cancel an agent
queue_add — send follow-up to a running agent
wait — block until an agent reaches a target phase

Getting Started

Core Concepts

Guides

spawn MCP tool

Parameters

Repo object

Response

Examples

Basic autonomous agent

With model and persona

Multi-repo spawn with branch overrides

Resume a dead agent

Fork from another agent

Flight execution

Forward environment variables

Fanout

Errors

​Parameters

​Repo object

​Response

​Examples

​Basic autonomous agent

​With model and persona

​Multi-repo spawn with branch overrides

​Resume a dead agent

​Fork from another agent

​Flight execution

​Forward environment variables

​Fanout

​Errors

​Related

Parameters

Repo object

Response

Examples

Basic autonomous agent

With model and persona

Multi-repo spawn with branch overrides

Resume a dead agent

Fork from another agent

Flight execution

Forward environment variables

Fanout

Errors

Related