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

> Trigger an image bake — runs the given recipe against a base image in the target environment and placement, then registers the new image.

Triggers an [image](/concepts/images) bake for a [recipe](/concepts/recipe). The bake combines a recipe (what to install), an [environment](/concepts/environments) (scratch VM shape), and a [placement](/concepts/environments) (where to run and which base image to use) to produce a provisioned image that agents use at spawn time.

If a matching image already exists in the cache, the command returns immediately without starting a new bake. Use `--force-new` to bypass the cache.

## Synopsis

```bash theme={null}
murmur bake [flags] <recipe> <environment> <placement>
```

## Arguments

| Name                | Type   | Required | Description                                                                                                                                                                                         |
| ------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recipe`            | string | yes      | Name of the [recipe](/concepts/recipe) to bake.                                                                                                                                                     |
| `environment`       | string | yes      | Name of the [environment](/concepts/environments) that provides the scratch VM shape.                                                                                                               |
| `placement`         | string | yes      | Name of the [placement](/concepts/environments) that determines where the image is baked and how the base image is resolved.                                                                        |
| `--force-new`       | bool   | no       | Skip the cache check and always run a fresh bake. Default: `false`.                                                                                                                                 |
| `--service-profile` | string | no       | Named [service profile](/catalog/service-profile) for credentials. Only available for GitHub App tenants. Mutually exclusive with `-e`.                                                             |
| `-e`                | string | no       | Forward an environment variable to the bake VM as a secret. `-e FOO` reads from your current environment; `-e FOO=bar` sets it explicitly. Repeatable. Mutually exclusive with `--service-profile`. |

## Output

The command prints one of three results depending on the state of the image cache:

### Cache hit

```
Image murmur-provision-a1b2c3d4e5f67890 already cached (hash: 9f86d081884c7d659a2feaa0c55ad015...)
```

The [image](/concepts/images) already exists. No bake is started.

### Bake started

```
Bake started (scope: acme-agents, image: murmur-provision-a1b2c3d4e5f67890, hash: 9f86d081884c7d659a2feaa0c55ad015...)
Pin workspace with: murmur patch workspace <name> --set image_ref=my-recipe-9f86d081884c7d65
```

A new bake is running. The output includes a [`murmur patch`](/cli/patch) command you can use to pin a [workspace](/concepts/workspaces) to the resulting [image](/concepts/images) once the bake completes.

### Bake already in progress

```
Bake in progress (scope: acme-agents, image: murmur-provision-a1b2c3d4e5f67890, hash: 9f86d081884c7d659a2feaa0c55ad015...)
```

A bake for this [image](/concepts/images) is already running. No duplicate bake is started.

## Examples

### Bake a recipe for staging

```bash theme={null}
murmur bake my-recipe staging us-central1
```

```
Bake started (scope: acme-agents, image: murmur-provision-a1b2c3d4e5f67890, hash: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08)
Pin workspace with: murmur patch workspace <name> --set image_ref=my-recipe-9f86d081884c7d65
```

### Force a fresh bake

```bash theme={null}
murmur bake --force-new my-recipe staging us-central1
```

Bypasses the cache and starts a new bake even if a matching [image](/concepts/images) already exists.

### Pass secrets to the bake VM

```bash theme={null}
murmur bake -e NPM_TOKEN -e ARTIFACTORY_URL=https://registry.example.com my-recipe staging us-central1
```

`-e NPM_TOKEN` reads the value from your current shell environment. `-e ARTIFACTORY_URL=https://registry.example.com` sets it explicitly. These secrets are available to the [recipe](/concepts/recipe) scripts during the bake.

### Use a service profile

```bash theme={null}
murmur bake --service-profile ci-bot my-recipe staging us-central1
```

Uses the `ci-bot` [service profile](/catalog/service-profile) for credentials instead of your developer profile.

## Errors

| Code                | Meaning                                                   | What to do                                                                                                                         |
| ------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `NOT_FOUND`         | The recipe, environment, or placement does not exist.     | Check the names with [`murmur get recipe`](/cli/get), [`murmur get environment`](/cli/get), or [`murmur get placement`](/cli/get). |
| `INVALID_ARGUMENT`  | `--service-profile and -e are mutually exclusive`         | Use one or the other, not both.                                                                                                    |
| `UNAUTHENTICATED`   | Identity token is missing or expired.                     | Run `murmur auth` or check your `murmur.local.yaml` configuration.                                                                 |
| `PERMISSION_DENIED` | You do not have `recipe.edit` permission for this tenant. | Contact your tenant admin.                                                                                                         |

## Related

* [Images](/concepts/images) — concept overview of the two-layer image model
* [Recipe](/concepts/recipe) — what a recipe defines
* [Custom images guide](/guides/custom-images) — end-to-end walkthrough of building custom images
* [`murmur bakes ls`](/cli/bakes-ls) — list bake workflows and their status
* [Placement](/catalog/placement) — catalog reference for placements
* [Environment](/catalog/environment) — catalog reference for environments