murmur spawn CLI command

Starts a new agent in a workspace. The agent provisions a VM, clones the workspace’s repositories, and begins working on the given task. The agent works independently and reports results. The agent clones the workspace’s repositories at the base branches that workspace declares, wherever you run the command from. Add --repo to clone a repository the workspace does not declare, or to pin a different base branch — including your own feature branch, which must be pushed to origin first, since the agent clones from the remote and not from your working tree.

Synopsis

murmur spawn [flags] <slug> [description]

The slug is a short identifier for this agent. It appears in status output, PR titles, and logs. The description is the task: everything after the slug is joined into a single string. The description is required unless --resurrect is set. Flags may appear before or after the positionals. A description word that starts with a dash is read as a flag; pass -- before the positionals to keep such words literal. When --flight is set, the slug is optional. It defaults to flight-<name>.

Arguments

Name	Type	Required	Description
`slug`	string	yes (unless `--flight` set)	Short identifier for the agent. Must be unique within the workspace. With `--flight`, defaults to `flight-<name>`.
`description`	string	yes (unless `--resurrect` set)	Task description. All words after the slug are joined. With `--flight`, it composes into the flight’s prompt as caller directives. With `--resurrect`, it may be omitted unless `--out`, `--output-schema`, or `--task` is set.
`--purpose`	string	no	One-sentence human-readable goal (max 240 chars). Shown in the dashboard.
`--agent`	string	no	Agent persona name from the catalog: a builtin such as `murmur-programmer` or `murmur-planner`, or one your tenant or workspace defines. A workspace persona of that name wins over a tenant persona, which wins over a builtin.
`--model`	string	no	Model name (e.g. `claude-opus-4-8`, `gpt-5-4`). Overrides the value in `murmur.yaml` and the persona’s model: see Model Selection for the full precedence chain. Implies the backend.
`--backend`	string	no	Override the inferred backend. Usually unnecessary: set automatically from `--model`.
`--reasoning-effort`	string	no	Reasoning effort: `low`, `medium`, `high`, `xhigh`, or `max`. Empty uses the model default.
`--service-profile`	string	no	Spawn under this service profile (a borrow that requires the `service-profile.assume` permission). Overrides the `service_profile` default set in `murmur.yaml`.
`--owner-mode`	string	no	Permanent owner of the agent: `caller` (default) or `service-profile`. `service-profile` requires `--service-profile` and makes the profile the agent’s owner.
`--daemon`	bool	no	Start the agent at a stable identity, or, if it already has an execution, deliver this request to it and wake it. A wake delivers the description, tasks, and attachments without replacing the agent’s configuration. Incompatible with `--force-new`, `--resurrect`, and `--fork-from`. Default: `false`.
`--image-ref`	string	no	Catalog image name (e.g. `python-a1b2c3d4e5f67890`) that this agent’s VM boots from instead of the workspace default. Not inherited on `--resurrect`: pass it again.
`--restrict-repository-access`	bool	no	Confine the agent to the repositories this spawn involves: the workspace’s repos, any `--repo`, their pull-request upstreams, and the workspace’s plugins. Its GitHub access is limited to that set. An operation reaching outside it is refused, and the agent holds no GitHub token of its own. Sticky per slug: a confined agent stays confined whether or not the flag is passed again. See Repository confinement. Default: `false`.
`--repo`	string	no	A repo to clone beyond the workspace’s, or a workspace repo whose base branch this spawn pins. Format: `URL`, `URL=base`, or `URL=base:working`. Repeatable, at most once per repository.
`--disable-current-branch-forking`	bool	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 flag each inherited repo uses its default branch instead. A top-level spawn rejects it. Default: `false`.
`--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.
`--output-schema`	string	no	JSON Schema for the agent’s structured answer: inline JSON, or `@path` to read it from a file. The answer is returned on the agent’s `structured_output`. A malformed schema is rejected.
`--attach`	string	no	Local file to attach privately to the agent’s first turn. Repeatable. Not supported for child agents, or for `--resurrect` without a description.
`--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 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.
`--folder`	string	no	Personal dashboard folder to file the agent under once it starts (e.g. `review`). Must name a folder you have already created with `murmur folder create`; the match ignores case. List yours with `murmur spawn-profiles`. Visible only to you: other viewers’ folders are unaffected. Top-level spawns only.
`--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`.
`--suggest-terminate-mode`	string	no	What `murmur suggest-terminate` does for this agent: `suggest` (show an advisory delete button) or `immediate` (terminate now). Empty uses the `suggest_terminate_mode` default from `murmur.yaml` when one is set, and otherwise inherits the workspace setting.
`--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`.
`--suppress-events`	string	no	GitHub event classes this agent ignores (never woken by), comma-separated: `ci` (CI results), `pr_comments` (PR comments and reviews). `none` forces full subscription, overriding a `suppress_events` default from `murmur.yaml` / `murmur.local.yaml`; empty inherits it. Suppressed events are still recorded on the agent’s timeline.
`--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 inherits `default_autopilot_timeout` from the workspace. Reconfigurable on a running agent with `murmur autopilot-timeout`.
`--workspace`	string	no	Workspace name. Required if not set in `murmur.yaml`.
`--wait`	bool	no	Block until the agent is terminal or at rest (task finished, idle, or sleeping with nothing queued). Prints a one-line outcome and the agent’s status on exit. Exits non-zero if the agent failed, was canceled, or reported an error. Default: `false`.
`--timeout`	int	no	With `--wait`, maximum seconds to block before failing. `0` means no client deadline. Default: `0`.
`--json`	bool	no	Print the `SpawnResponse` as JSON instead of the summary. With `--wait`, print the resulting `AgentStatus` as JSON. Default: `false`.
`--flight`	string	no	Flight 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_]*`, cannot start with `MURMUR_`, and cannot be a credential name such as `GH_TOKEN`, `CLAUDE_TOKEN`, or `SIGNING_KEY`: 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. Works with `--service-profile` as well; only `GH_TOKEN` is left to the profile.
`--propose`	bool	no	Stage a `SpawnAction` change-request `PENDING` for review instead of spawning. Requires a service profile (`--service-profile` or the `service_profile` default in `murmur.yaml`): a proposed spawn runs as the profile, never as you. Only the flags a `SpawnAction` carries are allowed: `--workspace`, `--service-profile`, `--agent`, `--model`, `--out`, `--tag`, `--on-idle` (`sleep` or `terminate`), `--purpose`, `--task`, `--reasoning-effort`, `--suppress-events`, `--dequeue-strategy`, `--suggest-terminate-mode`; any other flag fails loudly. Default: `false`.
`--rationale`	string	no	Rationale recorded on the change-request. Only with `--propose`.
`--completes-cr`	string	no	Complete the named open spawn-action change-request (e.g. `cr-a1b2c3d4e5f6`) 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`. Top-level spawns only.

Output

On success, prints the spawned agent’s slug and a summary of follow-up commands:

Spawned: fix-auth

  Dashboard:                                    https://murmur.example.com/github_app/acme/task/github_app%2Facme%2Fw%2Fbackend%2Fgithub_oauth%2Falice%2Ffix-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"

The Dashboard: line appears when the server returns a dashboard URL. With --json, the command prints the SpawnResponse as JSON instead. When --wait is set, the command blocks until the agent is terminal or at rest, then prints a one-line outcome (wait ended: …) and the agent’s full status (same format as murmur status). With --json, it prints only the AgentStatus as JSON.

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

Add a repo or override a base branch

murmur spawn --repo https://github.com/acme/frontend=main fix-styles Update button styles to match the new design system

The agent clones the workspace’s repositories by default. Use --repo to add a repository the workspace does not declare, or to override a workspace repository’s base branch. The format is URL, URL=base, or URL=base:working. Name each repository at most once. To start an agent from a branch you are working on, pin it:

git push -u origin HEAD
murmur spawn --repo https://github.com/acme/frontend=my-feature-branch fix-styles Finish the button restyle

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 is terminal or at rest, then prints the outcome and full status. Under the default on_idle: sleep policy, a finished agent rests rather than completing.

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. Values are encrypted by the server before they reach the agent’s VM. Set a variable on the top-level spawn to give it to the whole subtree; children inherit their parent’s secrets. Secret inheritance is independent of the identity the agent uses. A spawn under a service profile receives -e values alongside the profile’s credentials, while GH_TOKEN remains the profile’s minted GitHub token.

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.

Confine an agent to the repositories it works in

murmur spawn --restrict-repository-access triage-issues Triage the new issues

The agent may reach only the repositories this spawn involves: the workspace’s repos, their pull-request upstreams, and the workspace’s plugins, and holds no GitHub token of its own; each GitHub operation is authorized and credentialed individually. See Repository confinement for what changes for the commands the agent runs.

Propose a spawn for review

murmur spawn --propose --service-profile infra-bot --rationale "nightly dep bump" \
    bump-deps Update all Go dependencies and open a PR

created change-request cr-a1b2c3d4e5f6 for spawn of bump-deps (pending review)

Nothing spawns yet. The command stages a SpawnAction change-request as PENDING for review. A reviewer can approve it with a command such as murmur change-request approve. Approval executes the spawn under the infra-bot service profile, so the agent acts as the profile rather than the proposer or approver. Proposing requires change-request.create plus workspace.read; approval requires service-profile.assume on the profile.

Errors

Code	Meaning	What to do
`<slug> is already running`	An agent with this slug is already running (`ALREADY_EXISTS`).	Send a follow-up with `murmur queue add`, or use `--force-new` or `--resurrect` 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 login` or check your `murmur.local.yaml` configuration.
`--repo <url> given twice: name each repository once`	Two `--repo` flags name the same repository.	Combine them into one entry: `URL=base:working`.
`no folder named "<name>"`	`--folder` names a folder you have not created. The message lists your folders.	Create it with `murmur folder create`, or pass an existing name.
`--workspace is required`	No workspace is configured.	Pass `--workspace` or set the workspace in `murmur.yaml`.
`description is required`	No description was given and `--resurrect` is not set.	Add a task description after the slug.
`--out, --output-schema, --task require a description with --resurrect`	`--resurrect` was passed without a description alongside a flag that needs one. The message lists only the flags you passed.	Add a description, or drop those flags.
`--resurrect and --force-new are mutually exclusive`	Both flags were passed.	Use one or the other.
`flag provided but not defined: -<word>`	A dash-prefixed word in the description was read as a flag.	Pass `--` before the positionals to keep dash-prefixed words literal.
`service-profile ownership requires --service-profile`	`--owner-mode service-profile` was passed without a service profile.	Pass `--service-profile`.
`owner_mode must be caller or service_profile, got "<value>"`	`--owner-mode` has an unknown value.	Use `caller` or `service-profile`.
`--rationale only applies with --propose`	`--rationale` was passed on a direct spawn, which creates no change-request.	Add `--propose`, or drop `--rationale`.
`<flags> cannot be used with --propose — a SpawnAction change-request carries only ...`	A flag a `SpawnAction` change-request cannot express (e.g. `--repo`, `--wait`, `-e`) was passed with `--propose`.	Drop the flag: a proposed spawn carries only the slug, description, workspace, service profile, persona, model, expected output, tags, idle behavior, purpose, task checklist, reasoning effort, suppressed event classes, dequeue strategy, and suggest-terminate mode.
`--service-profile is required with --propose`	A proposed spawn is service-profile-owned; no profile was given and `murmur.yaml` sets no default.	Pass `--service-profile`, or set `service_profile` in `murmur.yaml`.
`repository access cannot be restricted to <repo>: it does not exist or is not covered by this tenant's GitHub App installation`	A repository in the derived set is not visible to your GitHub App installation, so it cannot be pinned. The message names which one.	Grant the App access to that repository, or take it out of the set: it came from the workspace’s repos, this command’s `--repo` entries, one of their pull-request upstreams, or the workspace’s plugins.

Agents: what agents are and how they work
Workspaces: the workspace that agents run in
Agent personas: predefined agent configurations
Tags: labels for grouping and filtering agents
Flights: multi-step flight plans
Repository confinement: confine an agent’s GitHub reach to the repositories its spawn involves
murmur status: check an agent’s current state
murmur ls: list running agents
murmur kill: cancel a running agent
murmur wait: block until an agent reaches a target phase
murmur queue add: send a follow-up message to a running agent
murmur ssh: open a shell on an agent’s VM

Getting Started

Core Concepts

Guides

murmur spawn CLI command

Synopsis

Arguments

Output

Examples

Spawn an autonomous agent

Spawn with a persona

Add a repo or override a base branch

Spawn in a specific workspace

Fork from another agent

Resurrect a previous session

Wait for completion

Forward environment variables

Execute a flight

Spawn with a task checklist

Tag an agent

Confine an agent to the repositories it works in

Propose a spawn for review

Errors

​Synopsis

​Arguments

​Output

​Examples

​Spawn an autonomous agent

​Spawn with a persona

​Add a repo or override a base branch

​Spawn in a specific workspace

​Fork from another agent

​Resurrect a previous session

​Wait for completion

​Forward environment variables

​Execute a flight

​Spawn with a task checklist

​Tag an agent

​Confine an agent to the repositories it works in

​Propose a spawn for review

​Errors

​Related

Synopsis

Arguments

Output

Examples

Spawn an autonomous agent

Spawn with a persona

Add a repo or override a base branch

Spawn in a specific workspace

Fork from another agent

Resurrect a previous session

Wait for completion

Forward environment variables

Execute a flight

Spawn with a task checklist

Tag an agent

Confine an agent to the repositories it works in

Propose a spawn for review

Errors

Related