> ## Documentation Index > Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt > Use this file to discover all available pages before exploring further. # spawn > MCP tool that creates a new autonomous or interactive Murmur agent with a persona, repo, and initial task — the primary entry point from MCP. Creates a new [agent](/concepts/agents). 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`](/mcp-server/queue-add) to send a follow-up instead. Equivalent to [`murmur spawn`](/cli/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-`. | | `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](/concepts/service-profiles) — borrowing a non-owned profile, which requires the `service-profile.assume` permission. Use [`spawn_profiles`](/mcp-server/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](#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`. | | `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). | | `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](/catalog/tag) 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. | ### 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 ```json theme={null} { "slug": "fix-auth-bug", "description": "Fix the authentication bypass in the login handler", "workspace": "backend", "out": "pr" } ``` Response: ```json theme={null} { "slug": "fix-auth-bug" } ``` ### With model and persona ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "slug": "fix-auth-bug", "resurrect": true, "description": "Continue fixing the auth bug — tests are still failing", "workspace": "backend" } ``` ### Fork from another agent ```json theme={null} { "slug": "fix-auth-v2", "fork_from": "fix-auth-bug", "description": "Try a different approach to the auth fix", "workspace": "backend", "out": "pr" } ``` ### Flight execution ```json theme={null} { "slug": "deploy-v2", "flight": "deploy.md", "flight_inputs": {"version": "2.1.0"}, "workspace": "platform" } ``` ### Fanout ```json theme={null} { "slug": "lint-{}", "description": "Run linter on {}", "each": "/tmp/repos.txt", "workspace": "platform", "out": "pr" } ``` Response: ```json theme={null} { "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`](/mcp-server/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. | ## Related * [`murmur spawn`](/cli/spawn) — equivalent CLI command * [Agents](/concepts/agents) — concept overview * [`status`](/mcp-server/status) — check agent state * [`ls`](/mcp-server/ls) — list running agents * [`kill`](/mcp-server/kill) — cancel an agent * [`queue_add`](/mcp-server/queue-add) — send follow-up to a running agent * [`wait`](/mcp-server/wait) — block until an agent reaches a target phase