> ## 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. # murmur spawn > Start a new Murmur agent — autonomous, interactive, or from a flight plan — with an explicit persona, repo, and initial task or prompt. Starts a new [agent](/concepts/agents) in a [workspace](/concepts/workspaces). The agent provisions a VM, clones the current repository at the current branch, and begins working on the given task. In autonomous mode, the agent works independently and reports results. In interactive mode, it runs in a tmux session you connect to with [`murmur ssh`](/cli/ssh). The current branch must be pushed to `origin` before spawning — the agent clones from the remote, not from your local working tree. ## Synopsis ```bash theme={null} murmur spawn [flags] [prompt...] ``` The `slug` is a short identifier for this agent — it appears in status output, PR titles, and logs. The `prompt` is the task description: everything after the slug is joined into a single string. The prompt is required in autonomous mode and optional in interactive mode. When `--flight` is set, the slug is optional — it defaults to `flight-`. ## Arguments | Name | Type | Required | Description | | ------------------------ | ------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `slug` | string | yes (unless `--flight` set) | Short identifier for the agent. Must be unique within the [workspace](/concepts/workspaces). With `--flight`, defaults to `flight-`. | | `prompt` | string | autonomous | Task description. Required for autonomous mode, optional for interactive mode. All words after the slug are joined. | | `-i` | bool | no | Interactive mode — the agent runs in a tmux session. Connect with [`murmur ssh`](/cli/ssh). Default: `false`. | | `--purpose` | string | no | One-sentence human-readable goal (max 240 chars). Shown in the dashboard. | | `--agent` | string | no | [Agent persona](/concepts/agent-personas) name (e.g. `programmer`, `architect`, `pm`). | | `--model` | string | no | Model name (e.g. `claude-opus-4-8`, `gpt-5-4`). Overrides the value in `murmur.yaml`. Implies the backend. | | `--backend` | string | no | Override the inferred backend. Usually unnecessary — set automatically from `--model`. | | `--service-profile` | string | no | Spawn under this [service profile](/concepts/service-profiles) (a borrow that requires the `service-profile.assume` permission). Overrides the `service_profile` default set in `murmur.yaml`. | | `--repo` | string | no | Additional repo to clone. Format: `URL`, `URL=base`, or `URL=base:working`. Repeatable. | | `--fork-from` | string | no | Fork from another agent's session. Pass the source agent's slug. The new agent starts with the source agent's context. Use a distinct slug to avoid branch name conflicts. | | `--resurrect` | bool | no | Restore context from a prior session for this slug. Mutually exclusive with `--force-new`. Default: `false`. | | `--force-new` | bool | no | Start fresh even if a prior session exists for this slug. Mutually exclusive with `--resurrect`. Default: `false`. | | `--append-system-prompt` | string | no | Text appended to the agent's system prompt. | | `--out` | string | no | Expected output artifact: `pr`, `push`, `respond`, or freeform text. | | `--task` | string | no | Checklist item the agent must complete. Repeatable — pass multiple `--task` flags for a multi-step checklist. | | `--tag` | string | no | Attach a [tag](/catalog/tag) by name for dashboard grouping and filtering. Repeatable, max 8. Each name must be a DNS-label slug (`[a-z0-9][a-z0-9-]{0,62}`); a name that does not yet exist is created automatically. | | `--pilot` | bool | no | Run with the completion assessor loop, which verifies the agent's work before marking the task complete. Default: `false`. | | `--stream` | bool | no | Use the streaming backend (long-lived session). Default: `false`. | | `--on-idle` | string | no | What happens when the agent finishes its task and has no follow-ups. Values: `sleep` (default), `terminate`, `keep-alive`. | | `--dequeue-strategy` | string | no | How the agent processes queued follow-ups. Values: `auto` (default — up to five follow-ups of one kind per turn; manual follow-ups and auto-generated events never share a turn), `all`, `one`, `five`. | | `--workspace` | string | no | [Workspace](/concepts/workspaces) name. Required if not set in `murmur.yaml`. | | `--wait` | bool | no | Block until the agent completes, fails, or goes idle. Prints the agent's status on exit. Default: `false`. | | `--flight` | string | no | [Flight](/concepts/flights) name. Resolves the flight from the tenant catalog and spawns a pilot agent to execute it. | | `--input` | string | no | Flight context input as `key=value`. Repeatable. Only valid with `--flight`. | | `-e` | string | no | Forward an environment variable to the agent as a secret. `-e FOO` reads from your current environment; `-e FOO=bar` sets it explicitly. Repeatable. Names must match `[A-Z][A-Z0-9_]*` and cannot start with `MURMUR_`. | ## Output On success, prints the spawned agent's slug and a summary of follow-up commands: ``` Spawned: fix-auth To get the status of the task: murmur status fix-auth To kill the task: murmur kill fix-auth To send a follow-up: murmur queue add fix-auth "additional context" ``` In interactive mode, an additional line shows how to connect: ``` To SSH into the VM: murmur ssh fix-auth ``` When `--wait` is set, the command blocks until the agent needs attention, then prints the agent's full status (same format as [`murmur status`](/cli/status)). ## Examples ### Spawn an autonomous agent ```bash theme={null} murmur spawn fix-auth Fix the JWT expiry validation in the auth middleware ``` ``` Spawned: fix-auth To get the status of the task: murmur status fix-auth To kill the task: murmur kill fix-auth To send a follow-up: murmur queue add fix-auth "additional context" ``` ### Spawn in interactive mode ```bash theme={null} murmur spawn -i explore-api ``` ``` Spawned: explore-api To get the status of the task: murmur status explore-api To kill the task: murmur kill explore-api To send a follow-up: murmur queue add explore-api "additional context" To SSH into the VM: murmur ssh explore-api ``` Connect with [`murmur ssh explore-api`](/cli/ssh) to interact with the agent directly. ### Spawn with a persona ```bash theme={null} murmur spawn --agent architect design-review Review the database schema for the new billing tables ``` The `--agent` flag selects an [agent persona](/concepts/agent-personas) — a predefined configuration that shapes the agent's behavior and system prompt. ### Override the repo and base branch ```bash theme={null} murmur spawn --repo https://github.com/acme/frontend=main fix-styles Update button styles to match the new design system ``` By default, the agent clones the repo and branch you are currently on. Use `--repo` to add additional repos or override the base branch. The format is `URL=base` or `URL=base:working`. ### Spawn in a specific workspace ```bash theme={null} murmur spawn --workspace backend fix-auth Fix the JWT expiry validation ``` If your `murmur.yaml` already sets a [workspace](/concepts/workspaces), you can omit `--workspace`. ### Fork from another agent ```bash theme={null} murmur spawn --fork-from fix-auth add-tests Write tests for the auth middleware changes ``` The new agent starts with all the context from the `fix-auth` agent's session. Always use a distinct slug when forking to avoid branch name conflicts. ### Resurrect a previous session ```bash theme={null} murmur spawn --resurrect fix-auth Continue where you left off on the auth fix ``` Restores the agent's prior context for the `fix-auth` slug. If a previous session is still shutting down, the command waits for it to finish before spawning. ### Wait for completion ```bash theme={null} murmur spawn --wait fix-auth Fix the JWT expiry validation ``` The command blocks until the agent completes, fails, or goes idle, then prints the agent's full status. ### Forward environment variables ```bash theme={null} murmur spawn -e API_KEY -e DATABASE_URL=postgres://localhost/mydb fix-auth Fix the auth middleware ``` `-e API_KEY` reads the value from your current shell environment. `-e DATABASE_URL=postgres://localhost/mydb` sets it explicitly. The agent receives these as environment variables on its VM. ### Execute a flight ```bash theme={null} murmur spawn --flight billing-migration --input customer_id=acme ``` Resolves the `billing-migration` [flight](/concepts/flights) from the tenant catalog and spawns a pilot agent to execute it. The slug defaults to `flight-billing-migration`. Pass `--input` to provide context variables the flight expects. ### Spawn with a task checklist ```bash theme={null} murmur spawn --task "Add input validation" --task "Write unit tests" --task "Update the README" fix-auth Improve the auth middleware ``` Each `--task` flag adds a checklist item the agent tracks and completes. ### Tag an agent ```bash theme={null} murmur spawn --tag release-blocker --tag backend fix-auth Fix the JWT expiry validation ``` Each `--tag` attaches a [tag](/catalog/tag) for grouping and filtering in the [dashboard](/guides/dashboard). A tag name that does not yet exist is created automatically. ## Errors | Code | Meaning | What to do | | ---------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `ALREADY_EXISTS` | An agent with this slug is already running. | Send a follow-up with [`murmur queue add`](/cli/queue-add), or use `--force-new` to replace the running agent. | | `INVALID_ARGUMENT` | A flag value is invalid (e.g. unknown dequeue strategy, invalid secret name). | Check the error message for the specific flag and correct the value. | | `UNAUTHENTICATED` | Identity token is missing or expired. | Run `murmur auth` or check your `murmur.local.yaml` configuration. | | `branch not found on origin` | The current git branch has not been pushed to `origin`. | Push your branch with `git push -u origin HEAD` and retry. | | `--workspace is required` | No [workspace](/concepts/workspaces) is configured. | Pass `--workspace` or set the workspace in `murmur.yaml`. | | `description required for autonomous mode` | No prompt was provided for an autonomous spawn. | Add a task description after the slug, or use `-i` for interactive mode. | | `--resurrect and --force-new are mutually exclusive` | Both flags were passed. | Use one or the other. | ## Related * [Agents](/concepts/agents) — what agents are and how they work * [Workspaces](/concepts/workspaces) — the workspace that agents run in * [Agent personas](/concepts/agent-personas) — predefined agent configurations * [Tags](/catalog/tag) — labels for grouping and filtering agents * [Flights](/concepts/flights) — multi-step flight plans * [`murmur status`](/cli/status) — check an agent's current state * [`murmur ls`](/cli/ls) — list running agents * [`murmur kill`](/cli/kill) — cancel a running agent * [`murmur wait`](/cli/wait) — block until an agent reaches a target phase * [`murmur queue add`](/cli/queue-add) — send a follow-up message to a running agent * [`murmur ssh`](/cli/ssh) — connect to an interactive agent's tmux session