workspace catalog resource

A workspace is a catalog resource that brings together everything an agent needs to run — an image, an environment, a placement, one or more repos, and optional secrets. When you spawn an agent, you specify a workspace and the platform uses it to provision the VM.

Fields

Name	Type	Required	Description
`name`	string	yes	Unique identifier. DNS label format: `[a-z][a-z0-9-]{0,62}`.
`image_ref`	string	yes	Image name. Must reference an existing image in the same tenant.
`environment_ref`	string	yes	Environment name. Must reference an existing environment in the same tenant.
`placement`	string	yes	Placement name. Must reference an existing placement in the same tenant.
`repos`	object[]	yes	One or more repos to clone. At least one is required. See Repo fields.
`min_idle`	int	no	Minimum warm VMs to keep idle in the pool. `0` disables prewarming. Default: `0`.
`secret_refs`	string[]	no	Secret names exposed to agents as environment variables. Each must reference an existing secret.
`runtime_secret_mounts`	object[]	no	Secrets delivered to agent VMs as environment variables or files. See Secret mount fields.
`ports`	object[]	no	Labeled ports surfaced in the dashboard. See Port label fields.
`description`	string	no	Human-readable description shown in the dashboard. Max 1024 bytes.
`preview_link_patterns`	string[]	no	RE2 regexps matched against the full URL of links in PR/review comments; matches become preview-link artifacts on the agent. Empty = none.
`tool_link_policy`	string	no	Tool link policy name selecting which MCP tool results become artifacts. Empty = the builtin `murmur-tool-links`. A named policy replaces the builtin.

Repo fields

Each entry in repos describes a repository the agent clones at startup.

Name	Type	Required	Description
`clone_url`	string	yes	HTTPS clone URL of the repository. Automatically canonicalized (trailing `.git` stripped).
`base_branch`	string	yes	Branch to branch from (e.g. `main`).
`conflict_resolution`	string	no	Strategy for file-changed events. Values: `MERGE` (default), `REBASE`, `NONE`. `NONE` opts out of file-changed notifications.

Clone URLs are canonicalized on write — https://github.com/acme/app.git becomes https://github.com/acme/app.

Secret mount fields

Each entry in runtime_secret_mounts declares how a secret is delivered to the agent VM.

Name	Type	Required	Description
`name`	string	yes	Name of an existing secret in the same tenant.
`mount_type`	string	yes	How the secret is delivered. Values: `ENV` (environment variable), `FILE` (written to disk).
`path`	string	conditional	Absolute file path on the VM. Required when `mount_type` is `FILE`.
`mode`	string	no	File permission mode in octal (e.g. `"0600"`). Defaults to `"0600"` for `FILE` mounts.
`env_name`	string	no	`ENV` mounts only. Environment variable the secret value is delivered as, instead of the secret name (which is then not exported). Must match `[A-Za-z_][A-Za-z0-9_]`; platform-delivered variables (`GH_TOKEN`, `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `OPENAI_API_KEY`, git plumbing, `MURMUR_`) are rejected. Empty delivers the secret under its own name.

File mount paths must be absolute and unique within a single workspace. Duplicate paths are rejected. Likewise, two ENV mounts may not deliver the same environment variable — each mount’s env_name (or secret name, when env_name is empty) must be unique.

Port label fields

Each entry in ports maps a TCP port number to a human-readable label shown in the dashboard.

Name	Type	Required	Description
`port`	int	yes	TCP port number (1–65535).
`label`	string	yes	Human-readable purpose (e.g. `"web"`, `"api"`).

Tool link capture

When an agent calls an MCP tool whose result contains links or identifiers — creating a Linear issue, a Jira ticket, a Notion page — matching links are captured as artifacts of that agent’s execution and shown alongside its uploads and preview links in the dashboard. Common MCP integrations are captured automatically: workspaces use the builtin murmur-tool-links policy by default (currently Linear issue writes, labeled by the issue identifier, e.g. MUR-123). To change what is captured, create your own tool link policy — copying the builtin’s entries if you want to keep them — and set tool_link_policy to its name. A policy with an empty patterns list disables capture.

Validation

The platform validates cross-resource consistency when you create or update a workspace:

The image and placement must target the same cloud provider. An image built for one provider cannot run on a placement configured for another.
For AWS placements, the image must be available in the placement region.
The image architecture must match the machine type architecture specified by the environment.
The environment cloud provider must match the placement cloud provider.
The machine type referenced by the environment must be available in the placement region.
You cannot remove a repo from a workspace if a flight trigger still references that repo.

Examples

Minimal workspace

name: default
image_ref: murmur-ubuntu-24
environment_ref: murmur-medium
placement: murmur-gcp-us-central1
repos:
  - clone_url: https://github.com/acme/backend
    base_branch: main

cat <<'EOF' | murmur set workspace default
name: default
image_ref: murmur-ubuntu-24
environment_ref: murmur-medium
placement: murmur-gcp-us-central1
repos:
  - clone_url: https://github.com/acme/backend
    base_branch: main
EOF

Workspace with secrets and port labels

name: fullstack
image_ref: murmur-ubuntu-24
environment_ref: murmur-large
placement: murmur-gcp-us-central1
repos:
  - clone_url: https://github.com/acme/backend
    base_branch: main
  - clone_url: https://github.com/acme/frontend
    base_branch: main
secret_refs:
  - npm-token
runtime_secret_mounts:
  - name: DOCKER_CONFIG_JSON
    mount_type: FILE
    path: /home/user/.docker/config.json
    mode: "0600"
  - name: NPM_PUBLISH_TOKEN
    mount_type: ENV
    env_name: NODE_AUTH_TOKEN
ports:
  - port: 3000
    label: web
  - port: 8080
    label: api
min_idle: 2
description: "Full-stack workspace with frontend and backend repos"

Listing workspaces

murmur get workspace

NAME        IMAGE               ENVIRONMENT    PLACEMENT                DESCRIPTION
default     murmur-ubuntu-24    murmur-medium  murmur-gcp-us-central1
fullstack   murmur-ubuntu-24    murmur-large   murmur-gcp-us-central1   Full-stack workspace with frontend and backend repos

Reading a single workspace

murmur get workspace default

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 DNS label: starts with a lowercase letter, only lowercase letters, digits, and hyphens, max 63 characters.
`INVALID_ARGUMENT`	`image_ref is required`	Set `image_ref` to the name of an existing image.
`INVALID_ARGUMENT`	`environment_ref is required`	Set `environment_ref` to the name of an existing environment.
`INVALID_ARGUMENT`	`placement is required`	Set `placement` to the name of an existing placement.
`INVALID_ARGUMENT`	`at least one repo is required`	Add at least one entry to `repos`.
`INVALID_ARGUMENT`	`repo clone_url is required`	Every repo entry needs a `clone_url`.
`INVALID_ARGUMENT`	`repo base_branch is required`	Every repo entry needs a `base_branch`.
`INVALID_ARGUMENT`	`image "<name>" does not exist`	The `image_ref` does not match any image in your tenant. Check the name with `murmur get image`.
`INVALID_ARGUMENT`	`environment "<name>" does not exist`	The `environment_ref` does not match any environment in your tenant. Check the name with `murmur get environment`.
`INVALID_ARGUMENT`	`placement "<name>" does not exist`	The `placement` does not match any placement in your tenant. Check the name with `murmur get placement`.
`INVALID_ARGUMENT`	`substrate mismatch: image "<image>" is <X> but placement "<placement>" is <Y>`	The image targets a different cloud provider than the placement. Use an image that matches.
`INVALID_ARGUMENT`	`image "<name>" not available in region "<region>"`	The image has no AMI in the placement region. Use an image available in that region.
`INVALID_ARGUMENT`	`architecture mismatch: image "<image>" is <X> but machine type "<mt>" is <Y>`	The image architecture does not match the machine type in the environment. Choose compatible resources.
`INVALID_ARGUMENT`	`machine type "<name>" is not available in region "<region>" (placement "<placement>")`	The machine type referenced by the environment is not offered in the placement region.
`INVALID_ARGUMENT`	`substrate mismatch: environment "<env>" is <X> but placement "<placement>" is <Y>`	The environment targets a different cloud provider than the placement.
`INVALID_ARGUMENT`	`secret_refs[<i>]: secret "<name>" does not exist`	A secret in `secret_refs` does not exist. Create it first with `murmur secret set`.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].name is required`	Every secret mount needs a `name`.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].mount_type is required`	Every secret mount needs a `mount_type` — either `ENV` or `FILE`.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].path is required for FILE mounts`	File mounts need an absolute `path`.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].path must be absolute`	The `path` must start with `/`.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>]: duplicate path "<path>"`	Two file mounts share the same path. Each must be unique.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].mode: invalid octal "<value>"`	The `mode` is not valid octal. Use a string like `"0600"`.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].env_name is only valid for ENV mounts`	`env_name` was set on a `FILE` mount. Use `path` to control where a `FILE` mount lands.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].path is only valid for FILE mounts`	`path` was set on an `ENV` mount. Use `env_name` to control the variable an `ENV` mount is delivered as.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].mode is only valid for FILE mounts`	`mode` was set on an `ENV` mount.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].env_name: "<value>" is not a valid environment variable name`	`env_name` must match `[A-Za-z_][A-Za-z0-9_]*`.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].env_name: "<value>" is reserved (would shadow a platform-delivered variable)`	The variable is delivered by the platform itself (`GH_TOKEN`, `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `OPENAI_API_KEY`, git plumbing, `MURMUR_*`). Pick another name.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>]: duplicate environment variable "<name>"`	Two `ENV` mounts deliver the same variable. Each mount’s `env_name` (or secret name when `env_name` is empty) must be unique.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>]: secret "<name>" does not exist`	A secret referenced by a mount does not exist. Create it first.
`INVALID_ARGUMENT`	`description exceeds 1024 byte limit (<n> bytes)`	Shorten the `description` to 1024 bytes or fewer.
`INVALID_ARGUMENT`	`preview_link_patterns[<i>]: ...`	The pattern is empty or not valid RE2. Fix the regexp.
`INVALID_ARGUMENT`	`tool_link_policy: tool link policy "<name>" does not exist`	The referenced tool link policy does not exist. Create it first, or leave the field empty for the builtin.
`FAILED_PRECONDITION`	`cannot delete workspace "<name>": referenced by flight: <flight>`	A flight references this workspace. Delete or update the flight first.
`FAILED_PRECONDITION`	`cannot remove repo "<url>" from workspace "<name>": flight "<flight>" trigger references it`	A flight trigger references this repo. Update the flight trigger before removing the repo.

Workspaces — concept overview
Placements — the placement resource a workspace references
Environments and placements — concept overview for environments
Images — the image resource a workspace references
Secrets — secrets referenced by secret_refs and runtime_secret_mounts
Flights — flights that reference a workspace
murmur set — CLI command for creating and updating catalog resources
murmur get — CLI command for reading catalog resources

Getting Started

Core Concepts

Guides

workspace catalog resource

Fields

Repo fields

Secret mount fields

Port label fields

Tool link capture

Validation

Examples

Minimal workspace

Workspace with secrets and port labels

Listing workspaces

Reading a single workspace

Errors

​Fields

​Repo fields

​Secret mount fields

​Port label fields

​Tool link capture

​Validation

​Examples

​Minimal workspace

​Workspace with secrets and port labels

​Listing workspaces

​Reading a single workspace

​Errors

​Related

Fields

Repo fields

Secret mount fields

Port label fields

Tool link capture

Validation

Examples

Minimal workspace

Workspace with secrets and port labels

Listing workspaces

Reading a single workspace

Errors

Related