Skip to main content
Starts a new agent in a workspace. 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. The current branch must be pushed to origin before spawning — the agent clones from the remote, not from your local working tree.

​
Synopsis

murmur spawn [flags] <slug> [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-<name>.

​
Arguments

NameTypeRequiredDescription
slugstringyes (unless --flight set)Short identifier for the agent. Must be unique within the workspace. With --flight, defaults to flight-<name>.
promptstringautonomousTask description. Required for autonomous mode, optional for interactive mode. All words after the slug are joined.
-iboolnoInteractive mode — the agent runs in a tmux session. Connect with murmur ssh. Default: false.
--purposestringnoOne-sentence human-readable goal (max 240 chars). Shown in the dashboard.
--agentstringnoAgent persona name (e.g. programmer, architect, pm).
--modelstringnoModel name (e.g. claude-opus-4-8, gpt-5-4). Overrides the value in murmur.yaml. Implies the backend.
--backendstringnoOverride the inferred backend. Usually unnecessary — set automatically from --model.
--service-profilestringnoSpawn under this service profile (a borrow that requires the service-profile.assume permission). Overrides the service_profile default set in murmur.yaml.
--repostringnoAdditional repo to clone. Format: URL, URL=base, or URL=base:working. Repeatable.
--fork-fromstringnoFork 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.
--resurrectboolnoRestore context from a prior session for this slug. Mutually exclusive with --force-new. Default: false.
--force-newboolnoStart fresh even if a prior session exists for this slug. Mutually exclusive with --resurrect. Default: false.
--append-system-promptstringnoText appended to the agent’s system prompt.
--outstringnoExpected output artifact: pr, push, respond, or freeform text.
--taskstringnoChecklist item the agent must complete. Repeatable — pass multiple --task flags for a multi-step checklist.
--tagstringnoAttach a 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.
--pilotboolnoRun with the completion assessor loop, which verifies the agent’s work before marking the task complete. Default: false.
--streamboolnoUse the streaming backend (long-lived session). Default: false.
--on-idlestringnoWhat happens when the agent finishes its task and has no follow-ups. Values: sleep (default), terminate, keep-alive.
--dequeue-strategystringnoHow 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.
--workspacestringnoWorkspace name. Required if not set in murmur.yaml.
--waitboolnoBlock until the agent completes, fails, or goes idle. Prints the agent’s status on exit. Default: false.
--flightstringnoFlight name. Resolves the flight from the tenant catalog and spawns a pilot agent to execute it.
--inputstringnoFlight context input as key=value. Repeatable. Only valid with --flight.
-estringnoForward 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).

​
Examples

​
Spawn an autonomous agent

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

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 to interact with the agent directly.

​
Spawn with a persona

murmur spawn --agent architect design-review Review the database schema for the new billing tables
The --agent flag selects an agent persona — a predefined configuration that shapes the agent’s behavior and system prompt.

​
Override the repo and base branch

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

murmur spawn --workspace backend fix-auth Fix the JWT expiry validation
If your murmur.yaml already sets a workspace, you can omit --workspace.

​
Fork from another agent

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

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

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

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

murmur spawn --flight billing-migration --input customer_id=acme
Resolves the billing-migration flight 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

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

murmur spawn --tag release-blocker --tag backend fix-auth Fix the JWT expiry validation
Each --tag attaches a tag for grouping and filtering in the dashboard. A tag name that does not yet exist is created automatically.

​
Errors

CodeMeaningWhat to do
ALREADY_EXISTSAn agent with this slug is already running.Send a follow-up with murmur queue add, or use --force-new to replace the running agent.
INVALID_ARGUMENTA flag value is invalid (e.g. unknown dequeue strategy, invalid secret name).Check the error message for the specific flag and correct the value.
UNAUTHENTICATEDIdentity token is missing or expired.Run murmur auth or check your murmur.local.yaml configuration.
branch not found on originThe current git branch has not been pushed to origin.Push your branch with git push -u origin HEAD and retry.
--workspace is requiredNo workspace is configured.Pass --workspace or set the workspace in murmur.yaml.
description required for autonomous modeNo 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 exclusiveBoth flags were passed.Use one or the other.