> ## 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.

# Workspaces

> How workspaces group repos, environments, placements, and secrets within a tenant so teams can share a launchable agent configuration.

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](/concepts/placement)** — where agent VMs run (platform-managed or customer-owned)
* **[Environment](/concepts/environments)** — what VMs look like (machine type, disk)
* **[Image](/concepts/images)** — the VM image agents boot from
* **[Secrets](/concepts/secrets)** — tenant secrets injected into agent VMs
* **Ports** — labeled ports for dashboard display (e.g. `3000: "dev server"`)

## Workspace vs tenant

| Concept       | Scope                                              | Example                          |
| ------------- | -------------------------------------------------- | -------------------------------- |
| **Tenant**    | Your GitHub org — the top-level isolation boundary | `acme-corp`                      |
| **Workspace** | A logical grouping within the tenant               | `backend`, `frontend`, `ml-team` |

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`](/cli/set). See the [workspace reference](/catalog/workspace) for all fields.

## 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`](/cli/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`](/cli/spawn).

***

| Type      | Page                                                    |
| --------- | ------------------------------------------------------- |
| Reference | [workspace](/catalog/workspace)                         |
| Reference | [`murmur set workspace`](/cli/set)                      |
| Reference | [`murmur spawn --workspace`](/cli/spawn)                |
| Guide     | [murmur.yaml configuration](/configuration/murmur-yaml) |
| Guide     | [Local overlays](/configuration/local-overlays)         |
| Concept   | [Placements](/concepts/placement)                       |
| Concept   | [Environments](/concepts/environments)                  |
| Concept   | [Images](/concepts/images)                              |
| Concept   | [Secrets](/concepts/secrets)                            |