spawn - Murmur

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`.
`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 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

{
  "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"
}

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

​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

​Fanout

​Errors

​Related