Skip to main content

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.

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

NameTypeRequiredDescription
namestringyesUnique identifier. DNS label format: [a-z][a-z0-9-]{0,62}.
image_refstringyesImage name. Must reference an existing image in the same tenant.
environment_refstringyesEnvironment name. Must reference an existing environment in the same tenant.
placementstringyesPlacement name. Must reference an existing placement in the same tenant.
reposobject[]yesOne or more repos to clone. At least one is required. See Repo fields.
min_idleintnoMinimum warm VMs to keep idle in the pool. 0 disables prewarming. Default: 0.
secret_refsstring[]noSecret names exposed to agents as environment variables. Each must reference an existing secret.
runtime_secret_mountsobject[]noSecrets delivered to agent VMs as environment variables or files. See Secret mount fields.
portsobject[]noLabeled ports surfaced in the dashboard. See Port label fields.
descriptionstringnoHuman-readable description shown in the dashboard. Max 1024 bytes.

​
Repo fields

Each entry in repos describes a repository the agent clones at startup.
NameTypeRequiredDescription
clone_urlstringyesHTTPS clone URL of the repository. Automatically canonicalized (trailing .git stripped).
base_branchstringyesBranch to branch from (e.g. main).
conflict_resolutionstringnoStrategy 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.
NameTypeRequiredDescription
namestringyesName of an existing secret in the same tenant.
mount_typestringyesHow the secret is delivered. Values: ENV (environment variable), FILE (written to disk).
pathstringconditionalAbsolute file path on the VM. Required when mount_type is FILE.
modestringnoFile permission mode in octal (e.g. "0600"). Defaults to "0600" for FILE mounts.
File mount paths must be absolute and unique within a single workspace. Duplicate paths are rejected.

​
Port label fields

Each entry in ports maps a TCP port number to a human-readable label shown in the dashboard.
NameTypeRequiredDescription
portintyesTCP port number (1–65535).
labelstringyesHuman-readable purpose (e.g. "web", "api").

​
Validation

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

​
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
    mount_type: FILE
    path: /home/user/.docker/config.json
    mode: "0600"
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

CodeMeaningWhat to do
INVALID_ARGUMENTname is requiredProvide a name field.
INVALID_ARGUMENTname 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_ARGUMENTimage_ref is requiredSet image_ref to the name of an existing image.
INVALID_ARGUMENTenvironment_ref is requiredSet environment_ref to the name of an existing environment.
INVALID_ARGUMENTplacement is requiredSet placement to the name of an existing placement.
INVALID_ARGUMENTat least one repo is requiredAdd at least one entry to repos.
INVALID_ARGUMENTrepo clone_url is requiredEvery repo entry needs a clone_url.
INVALID_ARGUMENTrepo base_branch is requiredEvery repo entry needs a base_branch.
INVALID_ARGUMENTimage "<name>" does not existThe image_ref does not match any image in your tenant. Check the name with murmur get image.
INVALID_ARGUMENTenvironment "<name>" does not existThe environment_ref does not match any environment in your tenant. Check the name with murmur get environment.
INVALID_ARGUMENTplacement "<name>" does not existThe placement does not match any placement in your tenant. Check the name with murmur get placement.
INVALID_ARGUMENTsubstrate 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_ARGUMENTimage "<name>" not available in region "<region>"The image has no AMI in the placement region. Use an image available in that region.
INVALID_ARGUMENTarchitecture 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_ARGUMENTmachine 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_ARGUMENTsubstrate mismatch: environment "<env>" is <X> but placement "<placement>" is <Y>The environment targets a different cloud provider than the placement.
INVALID_ARGUMENTsecret_refs[<i>]: secret "<name>" does not existA secret in secret_refs does not exist. Create it first with murmur secret set.
INVALID_ARGUMENTruntime_secret_mounts[<i>].name is requiredEvery secret mount needs a name.
INVALID_ARGUMENTruntime_secret_mounts[<i>].mount_type is requiredEvery secret mount needs a mount_type — either ENV or FILE.
INVALID_ARGUMENTruntime_secret_mounts[<i>].path is required for FILE mountsFile mounts need an absolute path.
INVALID_ARGUMENTruntime_secret_mounts[<i>].path must be absoluteThe path must start with /.
INVALID_ARGUMENTruntime_secret_mounts[<i>]: duplicate path "<path>"Two file mounts share the same path. Each must be unique.
INVALID_ARGUMENTruntime_secret_mounts[<i>].mode: invalid octal "<value>"The mode is not valid octal. Use a string like "0600".
INVALID_ARGUMENTruntime_secret_mounts[<i>]: secret "<name>" does not existA secret referenced by a mount does not exist. Create it first.
INVALID_ARGUMENTdescription exceeds 1024 byte limit (<n> bytes)Shorten the description to 1024 bytes or fewer.
FAILED_PRECONDITIONcannot delete workspace "<name>": referenced by flight: <flight>A flight references this workspace. Delete or update the flight first.
FAILED_PRECONDITIONcannot remove repo "<url>" from workspace "<name>": flight "<flight>" trigger references itA 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