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

The local murmur mcp server and the hosted MCP endpoint take the same parameters, with one exception: attachments exists only on the local server, and only off a VM. The hosted endpoint also rejects each and the bare form of env, because it has no local filesystem or caller environment.

Name	Type	Required	Description
`slug`	string	yes, unless `flight` is set	Agent task slug (e.g. `fix-auth-bug`). When `flight` is set, defaults to `flight-<name>`.
`description`	string	yes, unless `flight` is set	Complete, self-contained task instructions. The spawned agent does not inherit the caller’s conversation or context. It receives only what this request passes, so include all the context it needs. With `flight`, it composes into the flight’s prompt as caller directives.
`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.
`image_ref`	string	no	Catalog image name (e.g. `python-a1b2c3d4e5f67890`) that this agent’s VM boots from instead of the workspace default.
`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`). With `backend: opencode`, use `<connection>/<model>`, where the connection is an inference connection set up with `murmur setup connection add` (e.g. `openrouter/qwen/qwen3-coder`). A slash in the model alone selects `opencode`.
`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.
`owner_mode`	string	no	Permanent owner of the agent: `caller` (default) or `service_profile`. `service_profile` requires `service_profile` and permission to assume that profile.
`backend`	string	no	Coding agent backend: `claude` (default), `codex`, or `opencode`. Inferred from a `<connection>/<model>` model when omitted.
`reasoning_effort`	string	no	Reasoning effort level. Claude: `low`, `medium`, `high`, `xhigh`, `max`. Codex: `low`, `medium`, `high`, `xhigh`. Not accepted with `backend: opencode`. 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`. Matching workspace repos override their branch, and others are added. Top-level spawns only: a child inherits its parent’s repos. See Repo object.
`attachments`	string[]	no	Local file paths to attach privately to the agent’s first turn. Each path must name a regular file. Local `murmur mcp` server only, and not available on a VM: child agents cannot take attachments. Cannot be combined with `each`.
`session_mode`	string	no	`autonomous` (default) or `streaming`.
`completion_check`	string	no	`none` (default) or `assessor` (run completion assessor up to 3x before idling). A `flight` spawn defaults to `assessor`.
`on_idle`	string	no	Idle behavior: `sleep` (default), `terminate`, or `keep_alive`. `terminate` tears down the VM and loses session state.
`idle_timeout`	string	no	How long the agent waits idle before acting on `on_idle`, as a positive Go duration (e.g. `45m`), after a turn a person started or interacted with. A machine-triggered turn keeps the idle deadline at least one minute after it finishes, or for the configured idle timeout if that is shorter; it never moves an existing deadline earlier. Empty uses the platform default (`20m`).
`sleep_timeout`	string	no	How long the agent’s VM may stay asleep before the agent ends and the VM is released, as a Go duration between `1h` and `8760h` (e.g. `336h`). The clock starts when the VM sleeps, so a `keep_alive` agent never accrues it. Empty = the workspace default. `0` = no limit.
`autopilot_timeout`	string	no	How long the agent acts on CI results, PR comments, and merge conflicts on its own after the last human interaction, as a Go duration between `1m` and `8760h` (e.g. `72h`), or `0` for no limit. Once it lapses the agent turns those settings off and leaves them off until someone turns them back on. Empty = the workspace default.
`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`	string[]	no	GitHub event classes the agent ignores (never woken by): `ci` (CI results), `pr_comments` (PR comments and reviews). On the local server, omit it to inherit the `suppress_events` config default, or pass an empty list to force full subscription over it. On the hosted endpoint, omitting it means full subscription. Suppressed events are still recorded on the agent’s timeline.
`followups`	object	no	Per-event-class instructions, as a map from event class (`pr_merged`, `pr_comment`, `pr_review`, `ci_result`) to the prose the agent reads for that class. Plain text, not a template. It replaces murmur’s default instructions for that class. The event facts murmur formats are unaffected. Omit a class to keep the default, or the persona’s own override if it declares one. An unknown class name is rejected. Top-level spawns only.
`suggest_terminate_mode`	string	no	What `murmur suggest-terminate` does for this agent: `suggest` (show an advisory delete button) or `immediate` (terminate now). Empty inherits the workspace setting (`suggest` by default).
`resurrect`	boolean	no	Resume a completed/killed agent on the same branch with its full conversation history. Requires the same slug. Cannot be combined with `force_new`. 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.
`daemon`	boolean	no	Start the agent at a stable identity, or, if it already has an execution, deliver this request to it and wake it. Cannot be combined with `force_new`, `resurrect`, or `fork_from`.
`disable_current_branch_forking`	boolean	no	Child spawns only. By default a child agent’s inherited repos are based on the parent’s checked-out branch, which must be pushed. With this set, each inherited repo uses its default branch instead. Default: `false`.
`completes_change_request`	string	no	Complete the named open spawn-action change-request (e.g. `cr-a1b2c3`) with this spawn instead of approving its proposed action. Requires the change-request’s decide authority (`service-profile.assume` on its proposed profile), and the spawn must target the change-request’s workspace. Once the agent starts, the change-request is marked `APPLIED`. Cannot be combined with `each`.
`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.
`folder`	string	no	Personal dashboard folder to file the agent under once it starts. It must name one of your existing folders, as listed by `spawn_profiles`. An unknown name fails the spawn before anything starts. Visible only to the caller. Top-level spawns only.
`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.
`output_schema`	string	no	JSON Schema for the agent’s structured answer. The answer is returned on the agent’s `output.structuredOutput` in `status`. Empty means a plain response.
`flight`	string	no	Flight name in the tenant catalog (bare name, e.g. `deploy`). Runs the flight via a pilot agent. The flight’s settings fill any spawn parameters you leave unset.
`flight_inputs`	object	no	Context inputs for the flight, injected into the pilot prompt (e.g. `{"repo": "org/repo", "number": "42"}`). Only valid with `flight`: passing it without `flight` is an error.
`restrict_repository_access`	boolean	no	Confine this agent to the repositories its spawn declares: the workspace’s repos, any `repos` passed here, their pull-request upstreams, and the workspace’s plugins. Every GitHub operation must name one of them, and the agent holds no GitHub token of its own. A child spawn inherits the parent’s set exactly. Sticky per slug. See Repository confinement. Default: `false`.
`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. Local `murmur mcp` server only. Cannot be combined with `attachments` or `completes_change_request`.
`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 such as `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.
`destination_url`	string	no	HTTPS URL that receives the agent’s lifecycle events as webhook deliveries.
`destination_events`	string	with `destination_url`	Webhook subscription: a preset (`result`, `lifecycle`, `detail`) or a comma-separated list of classes (`result`, `phase`, `task`, `child`, `pr`, `cost`). `lifecycle` is `result` and `phase`. `detail` is every class.
`destination_context`	string	no	Opaque caller context echoed in every webhook delivery. Max 4096 bytes.
`signing_key`	string	with `destination_url`	Base64-encoded HMAC-SHA256 key (32 to 64 bytes) that murmur signs webhook deliveries with. Supplied by the trusted caller that sets up the webhook, not by the model.

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`). Empty resolves the repo’s default branch.
`branch`	string	no	Working branch for this repo. Overrides the top-level `branch`. Empty derives it from the agent’s identity.
`base_clone_url`	string	no	Clone URL of the repo the pull request is opened against, for a cross-repo PR (for example, working in a fork and targeting upstream). `clone_url` must be a fork of it. Empty opens a same-repo PR.

Response

Returns the slug of the spawned agent.

Field	Type	Description
`slug`	string	The slug of the spawned agent. With `owner_mode: service_profile`, the agent’s absolute path.
`dashboard_url`	string	The agent’s dashboard URL. Omitted when unavailable.

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

Field	Type	Description
`slugs`	string[]	Slugs of all spawned agents.
`count`	number	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",
  "dashboard_url": "https://murmur.example.com/github_app/acme/task/github_app%2Facme%2Fw%2Fbackend%2Fgithub_oauth%2Falice%2Ffix-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",
  "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, working, idle, or asleep.	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 name, 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