workspace catalog resource

A workspace is a catalog resource that brings together everything an agent needs to run: an image, an environment, a placement with the cloud identity VMs run as, zero 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}`.
`grants`	Grant[]	no	Who can read, use, or manage this workspace and its scoped resources. See Access grants.
`image_ref`	string	yes	Image name. Must reference an existing image in the same tenant.
`environment_ref`	string	conditional	Environment name. Must reference an existing environment in the same tenant. Required unless `placements` is set.
`placement`	string	conditional	Placement name. Must reference an existing placement in the same tenant. Required unless `placements` is set.
`service_account`	string	conditional	Cloud IAM identity agent VMs run as: a GCP service account email or an AWS instance profile ARN. Must match a service account binding on the placement. Required unless `placements` is set. Not used with `placements`.
`placements`	object[]	conditional	The placement, cloud identity, and environments this workspace approves, in preference order. Each entry has `placement`, `service_account`, and `environments` (one or more environment names). Agents launch on the first environment the platform can get capacity for. At most one entry. Mutually exclusive with `placement`, `environment_ref`, and `service_account`: set this list or those three.
`repos`	object[]	no	Repos to clone. A workspace may have none: its agents then run with no checkout. See Repo fields.
`min_idle`	int	no	Minimum warm VMs to keep idle in the pool. `0` disables prewarming. Default: `0`.
`runtime_secret_mounts`	object[]	no	Secrets delivered to agent VMs as environment variables or files. Each must reference an existing secret. 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_rules`	object[]	no	Which links in PR/review comments become preview-link artifacts on the agent, and how each is named and stored. At most 32. See Preview link rule fields. 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.
`plugins`	object[]	no	Plugins to install on agent VMs from git repos. Each entry has `clone_url` (HTTPS, required), `ref` (branch, tag, or SHA; empty = default branch), and `name` (required). Plugins from one repository must pin the same `ref`.
`port_proxy_disabled`	bool	no	When `true`, port-proxy is disabled for this workspace: no tunnels, no browser, SSH, or port-forward access. Default: `false`.
`disable_vm_editor`	bool	no	When `true`, the browser VS Code editor is unavailable for this workspace’s agents. Ordinary port access is unaffected. Default: `false`.
`suggest_terminate_mode`	enum	no	What `murmur suggest-terminate` does. `SUGGEST_TERMINATE_MODE_SUGGEST` (default) shows an advisory delete button; `SUGGEST_TERMINATE_MODE_IMMEDIATE` terminates the agent immediately.
`ignore_comment_body_patterns`	string[]	no	RE2 regexps matched unanchored against the body of PR comments and reviews. A matching comment does not wake the agent. Matching ignores the leading `[edited]` marker, and a dismissed review is always delivered. At most 32 patterns, each non-empty and at most 512 bytes. Empty = nothing is suppressed.
`default_sleep_timeout`	string	no	How long an agent’s VM may stay asleep before the agent ends and its VM is released, for spawns that set no sleep timeout of their own. A Go duration between `1h` and `8760h` (e.g. `336h`). An ended agent keeps its session, timeline, and events and can be resurrected. Empty (the default) = no limit.
`default_autopilot_timeout`	string	no	Default autopilot timeout for agents spawned in this workspace, as a Go duration between `1m` and `8760h` (e.g. `72h`): how long an agent acts on CI results, pull-request comments, and merge conflicts on its own after the last human interaction, before it turns those settings off and leaves them off until someone turns them back on. Empty (the default) sets no limit. A spawn can override it, including with `0` for no limit.

secret_refs is deprecated. A secret named there is not delivered to agent VMs. runtime_secret_mounts is the field that delivers one. To deliver a secret as an environment variable under its own name, declare it as a mount with mount_type: MOUNT_TYPE_ENV.

Access grants

The grants list controls access to this workspace. A grant names users or groups and supplies either a role or inline.permissions. It can also carry a name_pattern and extend_to_runtime_agents; see the grant fields.

Permission or role	Access supplied
`workspace.read`	Read the workspace configuration and see it in listings.
`workspace.use`	Access its contents, in addition to each resource’s own kind permission. Required for new spawns.
`workspace.edit` / `workspace.delete`	Edit or delete the workspace record.
`murmur-workspace-user`	`workspace.read`, `workspace.use`, and read access to scoped catalog resources. No `agent.*` permissions.
`murmur-workspace-manager`	Read, use, edit, and delete the workspace; manage its scoped catalog resources; run bakes; read, edit, and delete all its agents.

A workspace carries exactly the grants you save, on create and on update alike. An empty list grants nothing through the workspace: only tenant-bindings, such as a tenant admin binding, then decide who can use or manage it. The workspace creation defaults suggest three grants. The dashboard’s create form starts from them, and murmur defaults workspace prints them:

grants:
  - groups: [murmur-all-members]
    users: ["service-profile:*"]
    role: murmur-workspace-user
  - users: ["service-profile:murmur-image-updater"]
    role: murmur-image-updater-autonomous
    extend_to_runtime_agents: true
  - users: [your-login]
    role: murmur-workspace-manager

Every member and service profile may use the workspace.
The image-update service maintains the workspace’s environment automatically. See Automatic recipe updates.
You manage the workspace.

Remove or narrow any of them before you save; the workspace keeps only what you submit. Grants add authority; tenant-bindings still apply. Saving a workspace requires someone other than the image-update service to hold workspace.edit through its grants or a tenant-binding. An unpatterned tenant admin grant satisfies that requirement. Grants inherit onto agents in this workspace and catalog resources named {workspace}/{name}. The scoped kinds are recipe, image, environment, agent-persona, canned-response, knowledge, tool-link-policy, and secret. Reading secret metadata does not return its value. A grant on this workspace does not grant writes to tenant-level resources with bare names. Keep permissions checked against the bare workspace name (workspace.read, workspace.use, workspace.edit, workspace.delete, and bake.create) in a grant whose pattern matches that name. For example, use a separate unpatterned user grant alongside an agent.read grant patterned as github_oauth/alice/w/backend/*. extend_to_runtime_agents is evaluated live against the running agent’s acting identity. A grant on this workspace extends only to runtimes running here, not to runtimes in other workspaces.

Resource admission with `workspace_use`

Tenant-level resources of scoped kinds can be admitted to workspaces through their workspace_use policy. A placement’s service-account binding has its own policy of the same shape.

Field	Type	Required	Description
`workspace_use.scope`	enum	no	`WORKSPACE_USE_SCOPE_NONE` admits none, `WORKSPACE_USE_SCOPE_ALL` admits every workspace, or `WORKSPACE_USE_SCOPE_SELECTED` admits the names in `workspaces`. Omission admits none for a tenant-authored tenant-level resource.
`workspace_use.workspaces`	string[]	no	Workspace names matched by `WORKSPACE_USE_SCOPE_SELECTED`. Names must be DNS labels with no duplicates; they do not need to exist yet. Empty with other scopes.

Scoped resources are usable only within their own workspace. Platform builtins are usable in every workspace. Admission does not give a caller write permission. It also allows a running agent to receive extended read grants from its own workspace for an admitted tenant-level resource; direct reads otherwise use the caller’s grants. Changing workspace_use requires the resource kind’s edit permission through a tenant-binding, even when ordinary content edits are authorized by workspace grants. For a service-account binding, this permission is placement.edit on its placement.

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`	enum	no	Strategy for file-changed events. Values: `CONFLICT_RESOLUTION_MERGE` (default), `CONFLICT_RESOLUTION_REBASE`, `CONFLICT_RESOLUTION_NONE`. `CONFLICT_RESOLUTION_NONE` opts out of file-changed notifications.
`base_clone_url`	string	no	Base repo for a cross-repo PR. `clone_url` must be a fork of it. Empty opens a same-repo PR against `clone_url`’s own `base_branch`.

Clone URLs (including base_clone_url and plugin clone_url) 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: `MOUNT_TYPE_ENV` (environment variable), `MOUNT_TYPE_FILE` (written to disk).
`path`	string	conditional	Absolute file path on the VM. Required when `mount_type` is `MOUNT_TYPE_FILE`.
`mode`	string	no	File permission mode in octal (e.g. `"0600"`). Defaults to `"0600"` for file mounts.
`env_name`	string	no	Environment 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 environment 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"`).
`run_instructions`	string	no	Instructions for starting the service on this port. Delivered to the agent on port-proxy wake. Empty = a generic default.
`require_edit`	bool	no	When `true`, browser access to this port requires `agent.edit` instead of `agent.read`. Set it for ports that can act on the VM, such as a debugger or admin console.

Preview link rule fields

Each entry in preview_link_rules selects links in this workspace’s PR and review comments and says how a matching link is presented.

Name	Type	Required	Description
`pattern`	string	yes	RE2 regexp matched unanchored against the full URL of a link in a comment. At most 512 bytes. Anchor with `^…$` to require a full match. The pattern is the rule’s identity: the first rule matching a link owns it, and no two rules may repeat one.
`fixed_label`	string	no	The name every link matching this rule is shown under (e.g. `"Staging preview"`). At most 128 bytes, one line. Empty names each link from the link itself: its markdown text, else its host.
`coalesce`	bool	no	When `true`, this rule keeps one entry per agent and each matching link replaces its URL. Use it for a preview whose URL changes on every deploy, and pair it with `fixed_label` to give that entry a stable name: without one it is named by the link it currently holds. When `false` (default), every distinct matching URL becomes its own entry.
`authors`	string[]	no	GitHub usernames whose comments this rule extracts from, matched case-insensitively. A GitHub App comments under its bot login (e.g. `vercel[bot]`). Empty extracts from any comment author. Naming a bot here grants it no authority to wake or steer an agent.

A coalescing rule’s entry is identified by its pattern, so renaming fixed_label keeps the entry an agent already shows, while editing pattern starts a new one. Rule edits are forward-looking. Changing a rule governs what agents record from then on; an agent already running keeps the entries it recorded under the previous configuration, and every agent started after the change shows only the new behavior.

The pattern is the whole filter. When authors is empty, preview links are harvested from every PR and review comment regardless of who wrote it. Preview bots are usually not on any allowlist, so any link matching the pattern is surfaced no matter who posted it. Set authors to restrict a rule to named commenters.Anchor the pattern to hosts you control. A shared hosting apex like \.vercel\.app/ matches any customer’s deploy, including those outside your account. That matters most with fixed_label and coalesce: the label you choose becomes the visible name for whatever URL last matched, and a coalescing rule replaces its entry’s URL rather than adding beside it, so a matching link from anyone can take over the entry you named. The full URL is always shown in the entry’s tooltip.

preview_link_rules:
  - pattern: '^https://pr-\d+\.preview\.acme\.com/'
    fixed_label: Staging preview
    coalesce: true
  - pattern: '\.vercel\.app/'

Tool link capture

When an agent calls an MCP tool whose result contains links or identifiers, such as when creating a Linear issue, Jira ticket, or 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. Copy 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.
For GCP and AWS placements, service_account must match a service account binding on the placement.
You cannot remove a repo from a workspace if a flight trigger still references that repo.

Examples

Minimal workspace

This workspace has no grants, so only tenant-bindings decide who can use or manage it. Start from murmur defaults workspace to include the suggested grants.

name: default
image_ref: murmur-ubuntu-24
environment_ref: murmur-medium
placement: my-gcp
service_account: agent-runner@acme-agents-prod.iam.gserviceaccount.com
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: my-gcp
service_account: agent-runner@acme-agents-prod.iam.gserviceaccount.com
repos:
  - clone_url: https://github.com/acme/backend
    base_branch: main
EOF

Workspace with secret mounts and port labels

name: fullstack
image_ref: murmur-ubuntu-24
environment_ref: murmur-large
placement: my-gcp
service_account: agent-runner@acme-agents-prod.iam.gserviceaccount.com
repos:
  - clone_url: https://github.com/acme/backend
    base_branch: main
  - clone_url: https://github.com/acme/frontend
    base_branch: main
runtime_secret_mounts:
  - name: DOCKER_CONFIG_JSON
    mount_type: MOUNT_TYPE_FILE
    path: /home/user/.docker/config.json
    mode: "0600"
  - name: NPM_PUBLISH_TOKEN
    mount_type: 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

default
fullstack

The list prints one name per line.

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`	`placements is mutually exclusive with placement, environment_ref and service_account: clear the three legacy fields to use the list`	Set either `placements` or the `placement`, `environment_ref`, and `service_account` fields, not both.
`INVALID_ARGUMENT`	`placements: at most 1 entry is accepted, got <n>`	List one entry. Put alternatives in its `environments`.
`INVALID_ARGUMENT`	`grants: no grant on workspace "<name>" and no tenant binding confers workspace.edit on it ...`	Keep or add a `murmur-workspace-manager` grant, or have a tenant admin binding in place.
`INVALID_ARGUMENT`	`placements[0].environments must name at least one environment`	Add at least one environment name to the entry.
`INVALID_ARGUMENT`	`service_account is required for cloud placements`	Set `service_account` to an identity bound on the GCP or AWS placement.
`INVALID_ARGUMENT`	`service_account "<sa>" does not match any binding on placement "<placement>"`	Use an identity listed in the placement’s `service_account_bindings`.
`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 name in the deprecated `secret_refs` list matches no secret in your tenant. `secret_refs` delivers nothing to an agent VM either way: declare each secret in `runtime_secret_mounts` instead.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].name is required`	Every secret mount needs a `name`.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].name: secret name "<name>" must match [A-Z][A-Z0-9_]*`	Mount a secret whose name is a valid tenant secret name.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].mount_type is required`	Every secret mount needs a `mount_type`: either `MOUNT_TYPE_ENV` or `MOUNT_TYPE_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>].path "<path>" and "<other>" both resolve to <path>`	Two file mounts share the same path. Each must be unique.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].mode: invalid file mode "<value>": must be octal, at most 777: ...`	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 environment mount. Use `env_name` to control the variable an environment mount is delivered as.
`INVALID_ARGUMENT`	`runtime_secret_mounts[<i>].mode is only valid for FILE mounts`	`mode` was set on an environment 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>]: environment variable "<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 environment 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_rules[<i>].pattern: ...`	The rule’s pattern is empty, over 512 bytes, carries a NUL byte, or is not valid RE2. Fix the regexp.
`INVALID_ARGUMENT`	`preview_link_rules[<i>].fixed_label: ...`	The label is whitespace-only, over 128 bytes, or carries a control character. Give it one line of printable text, or omit it.
`INVALID_ARGUMENT`	`preview_link_rules[<i>].pattern: duplicates preview_link_rules[<j>] — a pattern is a rule's identity`	Two rules declare the same pattern. The first would own every link they both match, so merge them.
`INVALID_ARGUMENT`	`preview_link_rules: at most 32 rules, got <n>`	Reduce the rule count to 32 or fewer.
`INVALID_ARGUMENT`	`ignore_comment_body_patterns[<i>]: ...`	The pattern is empty, over 512 bytes, or not valid RE2.
`INVALID_ARGUMENT`	`ignore_comment_body_patterns: at most 32 patterns, got <n>`	Reduce the pattern count to 32 or fewer.
`INVALID_ARGUMENT`	`default_autopilot_timeout: ...`	Use a Go duration between `1m` and `8760h`, or leave it empty.
`INVALID_ARGUMENT`	`plugins[<i>]: ...`	Each plugin needs a `name` (a plain identifier, unique) and a valid `clone_url`. Plugins from one repository must pin the same `ref`.
`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 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

Access grants

Resource admission with `workspace_use`

Repo fields

Secret mount fields

Port label fields

Preview link rule fields

Tool link capture

Validation

Examples

Minimal workspace

Workspace with secret mounts and port labels

Listing workspaces

Reading a single workspace

Errors

​Fields

​Access grants

​Resource admission with workspace_use

​Repo fields

​Secret mount fields

​Port label fields

​Preview link rule fields

​Tool link capture

​Validation

​Examples

​Minimal workspace

​Workspace with secret mounts and port labels

​Listing workspaces

​Reading a single workspace

​Errors

​Related

Fields

Access grants

Resource admission with `workspace_use`

Repo fields

Secret mount fields

Port label fields

Preview link rule fields

Tool link capture

Validation

Examples

Minimal workspace

Workspace with secret mounts and port labels

Listing workspaces

Reading a single workspace

Errors

Related