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.
The Murmur catalog is a GCS-backed, per-tenant, versioned resource store. Every piece of Murmur configuration — workspaces, environments, secrets, roles, flights, and more — is a catalog resource with version history, audit metadata, and referential integrity.
What is the catalog?
The catalog is the single source of truth for all Murmur configuration. Rather than scattered config files or database tables, every configurable entity is stored as a versioned resource with:
- Kind — the type of resource (e.g.
workspace, secret, role)
- Name — unique identifier within its kind and tenant
- Fields — kind-specific configuration data
- Generation — monotonically increasing version number
- Author — who last modified the resource
- Timestamp — when it was last modified
Resources are stored in GCS, scoped to each tenant’s namespace. The API server mediates all access — no direct GCS reads or writes.
Resource kinds
The catalog contains 19 resource kinds organized into two categories:
Infrastructure resources
These define the compute infrastructure that agents run on:
| Kind | Purpose |
|---|
workspace | Top-level grouping of repos, environment, and agent defaults |
placement | Where VMs run: cloud provider, project, service account |
environment | VM specification: machine type, disk size, substrate |
pool-config | VM pool limits and scaling behavior (singleton) |
machine-type | Named VM sizes: vCPUs, memory, architecture |
image | VM/container image records from the bake process |
recipe | Image build recipes: base image, provisioning script |
repo-config | Per-repository configuration overrides |
Agent and identity resources
These define agent behavior, identity, and access control:
| Kind | Purpose |
|---|
agent | Runtime record of a spawned agent workflow |
agent-persona | Reusable persona definitions: prompt, model, tools |
flight | Stored flight documents with triggers and configuration |
secret | Tenant-wide secrets, KMS-encrypted at rest |
user-secret | Per-developer secrets, encrypted with developer AAD |
user | User identity: name, email, SSH keys |
role | Named permission sets |
group | User groups for bulk role assignment |
tenant-binding | Binds users/groups to roles at the tenant level |
alias | Name aliases for agent resources |
service-profile | Service identity and credentials configuration |
CRUD operations
CLI
The CLI provides five commands for catalog operations:
# Read a resource
murmur get workspace my-workspace
# Create or update a resource
murmur set workspace my-workspace
# Partial update (merge fields)
murmur patch workspace my-workspace --field repos[0].clone_url=https://...
# Delete a resource
murmur rm workspace my-workspace
# Describe a resource kind (schema, fields, constraints)
murmur describe workspace
Interactive editing
murmur set opens your $EDITOR with the resource’s current YAML (or a template for new resources). Save and close to apply changes.
# Edit an existing resource
murmur set environment my-env
# → Opens $EDITOR with current YAML
# → Save and close to apply
# Create from a file
murmur set workspace my-workspace -f workspace.yaml
API
The gRPC API provides equivalent RPCs:
| RPC | Purpose |
|---|
GetResource | Read a single resource |
SetResource | Create or update a resource |
ListResources | List resources of a kind |
DeleteResource | Delete a resource |
DescribeKinds | Get schema information for all kinds |
Version history
Every catalog edit creates a new generation. The catalog stores the full version history:
# View version history for a resource
murmur get workspace my-workspace --history
| Field | Description |
|---|
generation | Monotonically increasing version number (1, 2, 3, …) |
author | GitHub username of the person or agent who made the change |
timestamp | When the change was made (RFC 3339) |
fields | The complete resource state at this generation |
Reverting
You can revert a resource to a previous generation:
murmur get workspace my-workspace --generation 3
# View what generation 3 looked like
murmur set workspace my-workspace --revert-to 3
# Revert to generation 3 (creates a new generation with the old state)
Referential integrity
Resources can reference other resources. The catalog enforces referential integrity:
- A
workspace references an environment (via environment_ref)
- An
environment references a machine-type (via machine_type_ref)
- A
workspace references secret resources (via secret_refs)
- A
tenant-binding references a role and a group or user
When you attempt to delete a resource that is referenced by other resources, the deletion is blocked with an error listing the dependent resources:
Error: cannot delete machine-type "large" — referenced by:
environment "production" (field: machine_type_ref)
environment "staging" (field: machine_type_ref)
- Default pool-config — base pool settings
- Platform placements — the default platform-managed placement
- Base machine types — standard VM sizes
- Base images — the default agent VM image
Platform builtins are visible in murmur get and the dashboard catalog browser. They appear with a platform: true marker. You cannot modify or delete them, but you can create tenant-specific resources that override or extend them.
# List all machine types including platform builtins
murmur get machine-type --all
# Platform builtins are marked
# NAME VCPUS MEMORY PLATFORM
# small 2 8 true
# medium 4 16 true
# large 8 32 true
# my-custom 16 64 false
