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.
These catalog resources define the compute infrastructure that agents run on. They control where VMs are provisioned, what size they are, what software is pre-installed, and how repositories are handled.
workspace
The top-level resource that ties together repos, environment, and agent defaults. Every agent spawn targets a workspace.
Fields
| Field | Type | Required | Description |
|---|
name | string | Yes | Workspace identifier. Must be unique within the tenant. |
image_ref | string | No | Reference to a custom image resource. Overrides the base image. |
repos | array | No | List of repository configurations to clone on VMs. |
repos[].clone_url | string | Yes | Git clone URL for the repository. |
repos[].branch | string | No | Default branch to clone. Defaults to the repo’s default branch. |
placement | string | No | Reference to a placement resource. Defaults to platform-managed placement. |
min_idle | integer | No | Minimum number of warm (idle) VMs to keep in the pool for this workspace. |
environment_ref | string | No | Reference to an environment resource defining VM specs. |
secret_refs | array | No | List of secret resource names to inject into VMs. |
ports | array | No | Port configurations for tunneled services. |
ports[].port | integer | Yes | TCP port number. |
ports[].name | string | No | Human-readable name for the port. |
description | string | No | Human-readable description of the workspace’s purpose. |
Example
name: acme-backend
image_ref: custom-go-image
repos:
- clone_url: https://github.com/acme/backend.git
branch: main
- clone_url: https://github.com/acme/shared-libs.git
placement: platform
min_idle: 2
environment_ref: large-env
secret_refs:
- npm-token
- database-url
ports:
- port: 8080
name: api-server
description: "Backend API service workspace"
placement
Defines where VMs are provisioned — which cloud provider, project, and service account to use.
Fields
| Field | Type | Required | Description |
|---|
name | string | Yes | Placement identifier. |
platform | boolean | No | If true, this is a platform-managed placement. Default: false. |
substrate | string | No | Cloud substrate type (e.g. gce, aws). |
target | string | No | Cloud target specification. |
target.project | string | No | GCP project ID or AWS account. |
target.region | string | No | Cloud region. |
target.zone | string | No | Cloud zone. |
target.subnet | string | No | VPC subnet for the VMs. |
target.tags | array | No | Network tags applied to VMs. |
service_account | string | No | Service account for VMs to use. |
Example
name: customer-gcp
platform: false
substrate: gce
target:
project: acme-agents-prod
region: us-central1
zone: us-central1-a
subnet: projects/acme/regions/us-central1/subnetworks/agents
tags:
- agent-vm
service_account: agent-sa@acme-agents-prod.iam.gserviceaccount.com
Platform-managed placements (platform: true) use Murmur’s own infrastructure. Customer placements run VMs in your own cloud project, giving you control over networking, IAM, and compliance boundaries. See the Customer Placements guide for setup instructions.
environment
Defines the VM specification — machine type, disk size, and substrate.
Fields
| Field | Type | Required | Description |
|---|
name | string | Yes | Environment identifier. |
substrate | string | No | Cloud substrate type (e.g. gce, aws). |
machine_type_ref | string | No | Reference to a machine-type resource. |
disk_size_gb | integer | No | Boot disk size in GB. Default varies by platform. |
Example
name: large-env
substrate: gce
machine_type_ref: large
disk_size_gb: 100
pool-config
Controls VM pool behavior. This is a singleton — there is exactly one pool-config resource per tenant, always named default.
Fields
| Field | Type | Required | Description |
|---|
name | string | Yes | Always default. |
max_vms | integer | No | Maximum total VMs across the tenant. |
reap_stranded_agents | string | No | Auto-cleanup mode for agents whose VMs have disappeared: enabled, dry_run, or disabled. Default: dry_run. |
Example
name: default
max_vms: 50
reap_stranded_agents: enabled
The max_vms limit is tenant-wide. If you hit it, new agent spawns will wait in provisioning until existing VMs are released. Monitor pool status with murmur pool status or the dashboard’s pool view.
machine-type
Named VM sizes for reuse across environments.
Fields
| Field | Type | Required | Description |
|---|
name | string | Yes | Machine type identifier (e.g. small, large, gpu-enabled). |
vcpus | integer | Yes | Number of virtual CPUs. |
memory_gb | integer | Yes | Memory in gigabytes. |
architecture | string | No | CPU architecture: amd64 (default) or arm64. |
has_gpu | boolean | No | Whether the machine type includes GPU. Default: false. |
platform | boolean | No | If true, this is a platform-provided builtin. Immutable to tenants. |
Example
name: large
vcpus: 8
memory_gb: 32
architecture: amd64
has_gpu: false
image
Records of VM or container images, typically created by the bake process.
Fields
| Field | Type | Required | Description |
|---|
name | string | Yes | Image identifier. |
architecture | string | No | Target architecture: amd64 or arm64. |
source | string | No | Image source type: docker, aws, or gce. |
source.docker | object | No | Docker image reference. |
source.aws | object | No | AWS AMI reference. |
source.gce | object | No | GCE image reference with project and family/name. |
Example
name: custom-go-image
architecture: amd64
source:
gce:
project: acme-agents-prod
family: murmur-custom-go
recipe
Image build recipes used by murmur bake to produce custom images.
Fields
| Field | Type | Required | Description |
|---|
name | string | Yes | Recipe identifier. |
base_image_gce_ref | string | No | Base GCE image to build on. Typically the platform’s default image. |
base_image_aws_ref | string | No | Base AWS AMI to build on. |
provisioning_script | string | No | Shell script to run during the image build. Installs your toolchain. |
provisioning_timeout | string | No | Maximum time for the build to complete (Go duration). Default: 30m. |
secret_allowlist | array | No | List of secret names that can be accessed during the build (e.g. for private package registries). |
Example
name: go-docker-recipe
base_image_gce_ref: default
provisioning_script: |
#!/bin/bash
set -e
# Install Go
wget -q https://go.dev/dl/go1.22.0.linux-amd64.tar.gz
tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz
rm go1.22.0.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin
# Install Docker
curl -fsSL https://get.docker.com | sh
# Verify installations
go version
docker --version
provisioning_timeout: 20m
secret_allowlist:
- npm-token
murmur bake go-docker-recipe
repo-config
Per-repository configuration overrides. Applied to repos matching the clone_url.
Fields
| Field | Type | Required | Description |
|---|
name | string | Yes | Repo config identifier (typically the repo name). |
clone_url | string | Yes | Git clone URL this config applies to. |
conflict_resolution | string | No | How to handle merge conflicts: rebase (default) or merge. |
base_branch | string | No | Default base branch. Overrides the repository’s default branch. |
Example
name: backend-repo
clone_url: https://github.com/acme/backend.git
conflict_resolution: rebase
base_branch: main
