environment

An environment is a catalog resource that defines the compute shape of agent VMs. Each workspace references one environment via its environment_ref field. Environments are substrate-aware but placement-agnostic: the same environment can be reused across any placement that shares the same substrate.

Fields

Name	Type	Required	Description
`workspace_use`	object	no	For tenant-level names, which workspaces may use this resource: `scope` is `WORKSPACE_USE_SCOPE_NONE` (default), `WORKSPACE_USE_SCOPE_ALL`, or `WORKSPACE_USE_SCOPE_SELECTED` with a `workspaces` list. Scoped names carry no policy and are usable only in their own workspace. See resource admission.
`name`	string	yes	A bare tenant-level DNS label or `{workspace}/{name}`. Both segments match `[a-z][a-z0-9-]{0,62}`; a scoped name requires an existing workspace.
`substrate`	enum	yes	Cloud provider. Values: `SUBSTRATE_GCP`, `SUBSTRATE_AWS`.
`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. Must exist and match this environment’s substrate.
`disk_size_gb`	int	no	Boot disk floor in GiB — the size every VM starts at. Must be non-negative. `0` uses the image default, which a disk type provisioning IOPS or throughput cannot be paired with.
`disk_max_size_gb`	int	no	Boot disk ceiling in GiB — the largest size the disk auto-expands to as it fills. `0` applies the default ceiling (200 GiB, or the floor if the floor is larger), so auto-expand is on by default. Set equal to `disk_size_gb` to pin a fixed size. Must not be below the floor. Applies to both `SUBSTRATE_GCP` and `SUBSTRATE_AWS`. See Disk Sizing.
`description`	string	no	Human-readable description shown in the dashboard. Maximum 1024 bytes.
`provisioning_models`	enum[]	no	Provisioning models to allocate capacity from, in preference order: `PROVISIONING_MODEL_ON_DEMAND`, `PROVISIONING_MODEL_SPOT`. Empty means on-demand only. A VM falls back to the next model only when the cloud has no capacity left. Spot is supported on `SUBSTRATE_GCP`, and a Spot-only list is rejected when the machine type prices no Spot rate in any region.

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.On GCP, the two refs must also be compatible: a machine type that lists gce.supported_disk_types accepts only those disk types, and an environment naming one outside the list is rejected on write.An environment sets disk_size_gb and nothing else about the disk. Everything else the disk is created with, including its class and, for a provisioned-performance type, its IOPS and throughput, belongs to the disk type, so choosing a different performance level means referencing a different disk type.The disk type and disk_size_gb have to agree as well: a Hyperdisk volume’s capacity bounds the IOPS it can take. A disk_size_gb that is too small for the IOPS its disk type provisions is rejected when you write the environment or raise a disk type’s performance beyond a stored environment’s size. disk_size_gb: 0 takes the image’s own size, which only the created disk knows, so a disk type that provisions performance cannot be paired with it at all. See disk size and provisioned IOPS.

Examples

GCP environment

name: large
substrate: SUBSTRATE_GCP
machine_type_ref: murmur-n2-standard-64
disk_type_ref: murmur-pd-ssd
disk_size_gb: 600
description: "64 vCPU, 256 GB RAM for large codebases"

cat <<'EOF' | murmur set environment large
name: large
substrate: SUBSTRATE_GCP
machine_type_ref: murmur-n2-standard-64
disk_type_ref: murmur-pd-ssd
disk_size_gb: 600
description: "64 vCPU, 256 GB RAM for large codebases"
EOF

AWS environment

name: aws-default
substrate: SUBSTRATE_AWS
machine_type_ref: murmur-m5-xlarge
disk_type_ref: murmur-gp3
disk_size_gb: 200
description: "4 vCPU, 16 GB RAM general purpose"

Listing environments

murmur get environment

aws-default
large

The list prints one name per line, with no header.

Reading a single environment

murmur get environment large

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`name is required`	Provide a `name` field.
`INVALID_ARGUMENT`	`environment name must be a DNS label or {workspace}/{name}`	Use a bare DNS label or a scoped name whose two segments are DNS labels.
`INVALID_ARGUMENT`	`substrate is required`	Set the `substrate` field to `SUBSTRATE_GCP` or `SUBSTRATE_AWS`.
`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 `SUBSTRATE_GCP` or `SUBSTRATE_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.
`INVALID_ARGUMENT`	`machine type "..." does not support disk type "..." (gce.disk_type "..."): it supports ...`	The GCE machine type accepts only the disk types it lists in `gce.supported_disk_types`. Name one of those, or a machine type that accepts this disk type.
`INVALID_ARGUMENT`	`disk_size_gb=... with disk type "...": "..." provisions ... IOPS, which a ... GiB volume cannot take: GCE gives that volume ...`	Raise `disk_size_gb` until the volume reaches the IOPS its disk type provisions, or name a disk type provisioning fewer.
`INVALID_ARGUMENT`	`disk_size_gb=0 with disk type "...": "..." provisions performance, which needs the disk size stated: ...`	State a `disk_size_gb`, or name a disk type that derives its performance from capacity.
`INVALID_ARGUMENT`	`disk_size_gb=... with disk type "...": "..." takes a volume of ..., not ... GiB`	Set `disk_size_gb` within the range the disk type’s GCE family allows.
`INVALID_ARGUMENT`	`provisioning_models[<n>] repeats <model>`	List each provisioning model once.
`FAILED_PRECONDITION`	`cannot delete environment "...": referenced by workspace: ...`	Remove the workspace reference before deleting the environment.

Environments and placements: concept overview
Workspaces: the resource that references an environment
placement: catalog resource for cloud infrastructure targets
murmur set: CLI command for creating and updating catalog resources
murmur get: CLI command for reading catalog resources

Getting Started

Core Concepts

Guides

Fields

Examples

GCP environment

AWS environment

Listing environments

Reading a single environment

Errors

​Fields

​Examples

​GCP environment

​AWS environment

​Listing environments

​Reading a single environment

​Errors

​Related

Fields

Examples

GCP environment

AWS environment

Listing environments

Reading a single environment

Errors

Related