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.
Murmur uses a catalog-based authorization model. Org admins get full access by default. For finer control, define roles, create groups, and bind them to users. This page explains the permission system end to end.
Default access
Out of the box, Murmur provides two levels of default access based on GitHub org membership:
| GitHub role | Murmur access |
|---|
| Org admin | Full root access — all permissions on all resources |
| Org member | Basic access — can spawn agents, view status, manage own agents |
Permission model
Permissions are expressed as {kind}.{verb} strings. A permission grants the ability to perform a specific verb on a specific resource kind.
Kinds
Kinds correspond to catalog resource types and platform operations:
agent, secret, user-secret, placement, environment, workspace, pool-config, machine-type, image, recipe, repo-config, agent-persona, flight, user, role, group, tenant-binding, alias, service-profile
Verbs
| Verb | Description |
|---|
read | View a resource’s fields and metadata |
list | List resources of a kind |
create | Create new resources |
edit | Modify existing resources |
delete | Delete resources |
assume | Act as a resource (e.g., assume an agent identity) |
Examples
| Permission | Grants |
|---|
agent.create | Spawn new agents |
agent.edit | Modify agent state (kill, queue messages, update tasks) |
agent.read | View agent status and details |
secret.read | Read secret metadata (not values — values require secret.assume) |
placement.edit | Modify placement configurations |
workspace.delete | Delete workspace resources |
Wildcards
Wildcards let you grant broad permissions concisely:
| Pattern | Meaning |
|---|
* | All permissions on all kinds (root access) |
agent.* | All verbs on agents (read, list, create, edit, delete, assume) |
*.read | Read access on all kinds |
*.list | List access on all kinds |
secret.* | Full access to secrets |
Roles
Roles are catalog resources of kind role. A role defines a named set of permissions:
# murmur set role developer
name: developer
permissions:
- agent.create
- agent.edit
- agent.read
- agent.list
- agent.delete
- secret.read
- secret.list
- workspace.read
- workspace.list
Example roles
Observer (read-only)
name: observer
permissions:
- "*.read"
- "*.list"
Developer
name: developer
permissions:
- agent.create
- agent.edit
- agent.read
- agent.list
- agent.delete
- secret.read
- secret.list
- user-secret.create
- user-secret.edit
- user-secret.read
- user-secret.delete
- workspace.read
- workspace.list
- flight.read
- flight.list
Admin (full access)
name: admin
permissions:
- "*"
Groups
Groups organize users for bulk role assignment. Groups are catalog resources of kind group:
# murmur set group backend-team
name: backend-team
source: static
members:
- alice
- bob
- carol
Group sources
| Source | Description |
|---|
static | Members are explicitly listed in the group definition |
github_admin | Automatically includes all GitHub org admins |
all_tenant_members | Automatically includes all org members |
github_admin, all_tenant_members) automatically update as org membership changes — no manual member management required.
# All org members get this group's bindings
name: all-developers
source: all_tenant_members
# Only org admins get this group's bindings
name: platform-admins
source: github_admin
Tenant bindings
Tenant bindings connect users or groups to roles. They are catalog resources of kind tenant-binding:
# murmur set tenant-binding backend-developers
name: backend-developers
grant:
role_ref: developer
group_ref: backend-team
Binding a user directly
name: alice-admin
grant:
role_ref: admin
user_ref: alice
Binding a group
name: observers-binding
grant:
role_ref: observer
group_ref: all_tenant_members
observer role’s permissions in addition to their default access.
Per-resource grants
For fine-grained control, you can attach permissions directly to individual catalog resources. Per-resource grants restrict who can modify specific resources without affecting access to other resources of the same kind.
# On a specific placement resource
name: production-placement
grants:
- role_ref: admin
group_ref: platform-admins
platform-admins can modify the production-placement resource, even if other users have general placement.edit permission.
Name patterns
Permission grants can use name patterns to scope access to resources matching a pattern:
| Pattern | Matches |
|---|
${username} | Resources named with the current user’s GitHub username |
dev-* | Resources with names starting with dev- |
${username}/* | Resources under the user’s namespace |
name: self-service-agents
permissions:
- agent.create
- agent.edit:${username}/*
- agent.read:${username}/*
- agent.delete:${username}/*
Checking permissions
Use the CLI to check what permissions you (or another user) have:
# Check your own permissions
murmur check-permissions
# Check a specific permission
murmur check-permissions agent.create
# Check permissions for another user (requires admin access)
murmur check-permissions --user alice
Authorization flow
When an API request arrives, the authorization system evaluates permissions in this order:
- Identify the caller — extract identity from the token (user, agent, or service).
- Resolve memberships — determine which groups the caller belongs to.
- Collect grants — gather all role bindings (tenant-wide + per-resource) that apply to the caller.
- Flatten permissions — expand wildcards and merge all permission sets.
- Check — verify that the required
{kind}.{verb} permission exists in the flattened set.
- Allow or deny — if the permission is present, allow; otherwise, deny with a descriptive error.
Default org admin and org member access is applied before custom roles. Custom roles add to (not replace) the defaults.
