> ## 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 init

> Onboarding wizard that takes a repo from zero to a working Murmur workspace — installs the CLI, picks a recipe, bakes an image, and runs a test agent.

Launches an interactive onboarding session that creates a [recipe](/concepts/recipe), validates the provisioning script, and sets up a [workspace](/concepts/workspaces) for the target repo. Runs Claude Code with a specialized [persona](/concepts/agent-personas) that guides you through each step.

## Synopsis

```bash theme={null}
murmur init [flags] [directory]
```

## Arguments

| Name               | Type   | Required | Description                                                                                                                                  |
| ------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `directory`        | string | no       | Path to the project root. Default: current directory.                                                                                        |
| `--name`           | string | no       | [Recipe](/concepts/recipe) name. Default: derived from the git remote (slugified repo name).                                                 |
| `--workspace-name` | string | no       | [Workspace](/concepts/workspaces) name. Default: inherited from `murmur.yaml`, or falls back to the recipe name.                             |
| `--environment`    | string | no       | Target [environment](/concepts/environments). Default: discovered or prompted during the session.                                            |
| `--placement`      | string | no       | Target [placement](/concepts/environments). Default: discovered or prompted during the session.                                              |
| `--overwrite`      | bool   | no       | Replace an existing [recipe](/concepts/recipe) and [workspace](/concepts/workspaces) with the same name without prompting. Default: `false`. |

## Prerequisites

[`murmur init`](/cli/init) checks these prerequisites before starting:

* **Project root** — The directory contains at least one recognized project marker (`.git`, `go.mod`, `package.json`, `pyproject.toml`, `Cargo.toml`, `Gemfile`, or `Makefile`).
* **Claude Code** — `claude` is on your `PATH`. Install with `npm install -g @anthropic-ai/claude-code`.
* **Claude authentication** — `claude auth status` succeeds. Run `claude auth login` if not.
* **MCP server** — The murmur MCP server is configured in Claude Code. Run `claude mcp add murmur -- murmur mcp` if not.
* **murmur setup** — A valid `.murmur/murmur.yaml` exists. Run [`murmur setup`](/cli/setup) first.

## What it does

The onboarding session runs as an interactive Claude Code conversation. The [persona](/concepts/agent-personas) drives a workflow that:

1. Inspects the repo to understand languages, frameworks, and build tools.
2. Creates a provisioning script (`.murmur/provisioning.sh`) that installs dependencies and prepares the environment.
3. Validates the script by running a bake-iterate-fix loop until the image builds cleanly.
4. Creates the [recipe](/concepts/recipe) and [workspace](/concepts/workspaces) in the [catalog](/catalog/overview).
5. Optionally runs a smoke test by [spawning](/cli/spawn) a test [agent](/concepts/agents).

After the session completes, [`murmur init`](/cli/init) persists the [workspace](/concepts/workspaces) name to `murmur.yaml` so that [`murmur spawn`](/cli/spawn) uses it by default.

<Note>
  The onboarding session runs on your machine, not in a sandbox. Read-only operations and writes to `.murmur/` are auto-approved. Other operations prompt you for confirmation.
</Note>

<Card title="Why murmur init passes --dangerously-load-development-channels" icon="lightbulb-exclamation-on">
  Under the hood, `murmur init` launches Claude Code with `--dangerously-load-development-channels server:murmur`. The flag opts the session into Claude Code's channel transport, which Murmur uses to stream real-time [events](/concepts/events) (bake progress, smoke-test status, child lifecycle) from the control plane into your conversation as `<channel>` tags. Without it the onboarding persona can't observe the bake-iterate-fix loop or the test [`spawn`](/cli/spawn), and the session falls back to blind polling.

  The `dangerously-` prefix is Claude Code's wording for an opt-in developer feature, not a security warning specific to Murmur. The same flag is also used by [`murmur director`](/cli/director) and by every interactive agent VM that Murmur spawns, so all sessions can post to and receive from `server:murmur`.

  **When Claude Code prompts you to confirm channels, say yes and opt in.** The wizard can't observe the bake without it.
</Card>

## Examples

### Onboard the current repo

```bash theme={null}
murmur init
```

### Onboard a different directory

```bash theme={null}
murmur init /path/to/my-project
```

### Onboard with explicit names

```bash theme={null}
murmur init --name my-api --workspace-name backend
```

### Replace an existing recipe and workspace

```bash theme={null}
murmur init --overwrite
```

## Errors

| Code                                 | Meaning                                                   | What to do                                                                                        |
| ------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `no project detected`                | The target directory has no recognized project marker.    | Run [`murmur init`](/cli/init) from a project root, or pass the project directory as an argument. |
| `claude not found`                   | Claude Code is not installed.                             | Install with `npm install -g @anthropic-ai/claude-code`.                                          |
| `claude not authenticated`           | Claude Code is not logged in.                             | Run `claude auth login`.                                                                          |
| `murmur MCP server not configured`   | The murmur MCP server is not registered with Claude Code. | Run `claude mcp add murmur -- murmur mcp`.                                                        |
| `not configured — run: murmur setup` | No `.murmur/murmur.yaml` found.                           | Run [`murmur setup`](/cli/setup) to create the config file.                                       |

## Related

* [Recipes](/concepts/recipe) — what a recipe defines
* [Workspaces](/concepts/workspaces) — concept overview
* [Agent personas](/concepts/agent-personas) — how personas guide agent behavior
* [`murmur setup`](/cli/setup) — configure your developer profile (prerequisite)
* [`murmur spawn`](/cli/spawn) — start an agent in the workspace created by init
* [Catalog: recipe](/catalog/recipe) — the recipe resource
* [Catalog: workspace](/catalog/workspace) — the workspace resource