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 the top-level organizational unit within a Murmur tenant. It groups repositories, references an environment and placement, and defines the default configuration for agents spawned within it.

​
What is a workspace?

A workspace is a catalog resource (workspace kind) that binds together:
  • Repos — which repositories agents can clone, with optional base branch overrides
  • Placement — where agent VMs run (platform-managed or customer-owned)
  • Environment — what VMs look like (machine type, disk, image)
  • Image — the VM image agents boot from
  • Secrets — tenant secrets injected into agent VMs
  • Ports — labeled ports for dashboard display (e.g., 3000: "dev server")

​
Workspace vs tenant

ConceptScopeExample
TenantYour GitHub org — the top-level isolation boundaryacme-corp
WorkspaceA logical grouping within the tenantbackend, frontend, ml-team
A tenant can have multiple workspaces. Each workspace can reference different environments, placements, and repos. Having multiple workspaces lets different teams within the same org use different VM sizes, cloud regions, or toolchain images.

​
Creating a new workspace

There are two ways to create a new workspace:
  1. Create workspace from Murmur UI You can create a new workspace from the Murmur UI, from Organization Settings → Workspaces,
  2. Create workspace from the CLI You can also create a new workspace directly from your command line:
cat <<EOF | murmur set workspace backend-team
name: backend-team
image_ref: go-python
environment_ref: default
placement: us-central1
repos:
  - clone_url: https://github.com/acme-corp/api-server
    base_branch: main
  - clone_url: https://github.com/acme-corp/shared-libs
secret_refs:
  - INTERNAL_API_KEY
  - DATABASE_URL
description: "Backend team workspace with Go and Python toolchain"
EOF

​
How does Murmur CLI/MCP know which workspace to use?

When you run murmur spawn from the CLI or call the spawn tool over MCP, the server needs to know which workspace to operate in: because the workspace defines the repos, environment, placement rules, etc. that the agent will use. There are three places that workspace can come from:
  1. .murmur/murmur.yaml (the team default, checked into the repo) This is the baseline config that lives in your repo. The field is: workspace: <my-team-workspace> . Because this file is committed, every teammate who clones the repo gets this same config.
  2. .murmur/murmur.local.yaml (the per-developer override, gitignored) This follows the same schema as .murmur/murmur.local.yaml , but it’s a local overlay that is not checked in. This overrides any team default in .murmur/murmur.yaml .
  3. Per-spawn override (highest priority) Every spawn accepts a workspace argument that will trump anything in the .yamlconfig files. For example: 
    murmur spawn --workspace frontend-team fix-css "Fix the responsive layout"

​
Multiple repos

A workspace can reference multiple repositories. When an agent spawns, it clones all repos in the workspace. You can override which repos an agent uses with the --repo argument: 
murmur spawn --repo https://github.com/acme-corp/api-server=main task "Work on the API"
The --repo format is URL, URL=base_branch, or URL=base_branch:working_branch.