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

# environment

> Catalog resource that defines the compute shape for agent VMs — cloud substrate, machine type, disk type, disk size, and architecture.

An [environment](/concepts/environments) is a catalog resource that defines the compute shape of agent VMs. Each [workspace](/concepts/workspaces) references one [environment](/concepts/environments) via its `environment_ref` field.

[Environments](/concepts/environments) are substrate-aware but [placement](/concepts/placement)-agnostic — the same [environment](/concepts/environments) can be reused across any [placement](/concepts/placement) that shares the same substrate.

## Fields

| Name               | Type   | Required    | Description                                                                                                                                      |
| ------------------ | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`             | string | yes         | Unique identifier. DNS label format: `[a-z][a-z0-9-]{0,62}`.                                                                                     |
| `substrate`        | string | yes         | Cloud provider. Values: `GCP`, `AWS`, `DOCKER`.                                                                                                  |
| `machine_type_ref` | string | yes         | Name of a machine-type resource. Must exist and match this environment's substrate.                                                              |
| `disk_type_ref`    | string | conditional | Name of a disk-type resource. Required for `GCP` and `AWS` substrates. Optional for `DOCKER`. Must exist and match this environment's substrate. |
| `disk_size_gb`     | int    | no          | Boot disk size in GiB. `0` uses the image default. Must be non-negative.                                                                         |
| `description`      | string | no          | Human-readable description shown in the dashboard. Maximum 1024 bytes.                                                                           |

<Note>
  The `machine_type_ref` and `disk_type_ref` must reference resources whose substrate matches the environment's substrate. A substrate mismatch is rejected on write.
</Note>

## Examples

### GCP environment

```yaml theme={null}
name: large
substrate: GCP
machine_type_ref: n2-standard-64
disk_type_ref: pd-ssd
disk_size_gb: 600
description: "64 vCPU, 256 GB RAM for large codebases"
```

```bash theme={null}
cat <<'EOF' | murmur set environment large
name: large
substrate: GCP
machine_type_ref: n2-standard-64
disk_type_ref: pd-ssd
disk_size_gb: 600
description: "64 vCPU, 256 GB RAM for large codebases"
EOF
```

### AWS environment

```yaml theme={null}
name: aws-default
substrate: AWS
machine_type_ref: m7i-xlarge
disk_type_ref: gp3
disk_size_gb: 200
description: "4 vCPU, 16 GB RAM general purpose"
```

### Listing environments

```bash theme={null}
murmur get environment
```

```
NAME          SUBSTRATE  MACHINE TYPE REF  DISK SIZE GB  DESCRIPTION
default       GCP        n2-standard-8     0             Platform default
large         GCP        n2-standard-64    600           64 vCPU, 256 GB RAM for large codebases
aws-default   AWS        m7i-xlarge        200           4 vCPU, 16 GB RAM general purpose
```

### Reading a single environment

```bash theme={null}
murmur get environment large
```

## Errors

| Code                  | Meaning                                                                          | What to do                                                                                                     |
| --------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `INVALID_ARGUMENT`    | `name is required`                                                               | Provide a `name` field.                                                                                        |
| `INVALID_ARGUMENT`    | `name must match [a-z][a-z0-9-]{0,62}`                                           | Use a lowercase DNS label for the name.                                                                        |
| `INVALID_ARGUMENT`    | `substrate is required`                                                          | Set the `substrate` field to `GCP`, `AWS`, or `DOCKER`.                                                        |
| `INVALID_ARGUMENT`    | `machine_type_ref is required`                                                   | Provide a `machine_type_ref` that names an existing machine-type resource.                                     |
| `INVALID_ARGUMENT`    | `disk_size_gb must be non-negative`                                              | Set `disk_size_gb` to `0` or a positive integer.                                                               |
| `INVALID_ARGUMENT`    | `disk_type_ref is required for GCP and AWS substrates`                           | Provide a `disk_type_ref` when the substrate is `GCP` or `AWS`.                                                |
| `INVALID_ARGUMENT`    | `description exceeds 1024 byte limit`                                            | Shorten the `description` to 1024 bytes or fewer.                                                              |
| `INVALID_ARGUMENT`    | `machine_type_ref "..." does not exist`                                          | The referenced machine-type resource does not exist. Create it first or correct the name.                      |
| `INVALID_ARGUMENT`    | `disk_type_ref "..." does not exist`                                             | The referenced disk-type resource does not exist. Create it first or correct the name.                         |
| `INVALID_ARGUMENT`    | `substrate mismatch: machine type "..." is ... but environment substrate is ...` | The machine-type resource targets a different substrate than the environment. Use a machine type that matches. |
| `INVALID_ARGUMENT`    | `substrate mismatch: disk type "..." is ... but environment substrate is ...`    | The disk-type resource targets a different substrate than the environment. Use a disk type that matches.       |
| `FAILED_PRECONDITION` | `cannot delete environment "...": referenced by workspace: ...`                  | Remove the workspace reference before deleting the environment.                                                |

## Related

* [Environments and placements](/concepts/environments) — concept overview
* [Workspaces](/concepts/workspaces) — the resource that references an environment
* [placement](/catalog/placement) — catalog resource for cloud infrastructure targets
* [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources
* [`murmur get`](/cli/get) — CLI command for reading catalog resources