Skip to main content
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 a workspace 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: 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

A tenant can have multiple workspaces. Each workspace can reference different environments, placements, and repos. Multiple workspaces let different teams within the same org use different VM sizes, cloud regions, or toolchain images.

​
Creating a workspace

Create workspaces from the dashboard (Organization Settings → Workspaces) or with murmur set workspace. See the workspace reference for all fields.

​
Access

A workspace’s grants name who can see its configuration, use its contents, or manage it. workspace.read controls configuration visibility and listings; workspace.use is the additional permission needed to access its contents or spawn into it. Managers can also manage scoped resources and all agents in that workspace. Members can create workspaces. A workspace carries exactly the grants saved with it. The creation defaults suggest grants that admit members and service profiles, enable Automatic image updates, and make you a manager; the dashboard’s create form starts from them. With no grants, only tenant-bindings, such as a tenant admin binding, decide who can use or manage the workspace. See access grants.

​
Workspace resolution

When you spawn an agent, the workspace is resolved from three sources in order of priority:
  1. Per-spawn override: the --workspace flag on murmur spawn
  2. Local overlay: workspace field in .murmur/murmur.local.yaml (gitignored, per-developer)
  3. Team default: workspace field in .murmur/murmur.yaml (checked in)

​
Multiple repos

A workspace can reference multiple repositories. When an agent spawns, it clones all repos in the workspace. Override per-spawn with the --repo flag on murmur spawn.