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

# runtime-role catalog resource

> Catalog resource that bounds the Murmur platform permissions an agent holds: what it may do in Murmur, always within its owner's current access.

A runtime role bounds the Murmur API calls an [agent](https://docs.murmur.dev/concepts/agents.md) may make: spawning and managing agents, reading catalog resources, proposing change requests. The dashboard shows it as **Permissions → Platform** on the agent.

A request the agent makes is allowed only when both of these allow it:

1. the agent's runtime role, and
2. its recorded owner's **current** [permissions](https://docs.murmur.dev/security/authorization.md).

Both are checked on every request, so revoking a permission from the owner removes it from all of the owner's agents immediately. A runtime role never grants anything the owner lacks.

## Synopsis

```bash theme={null}
murmur get runtime-role [name]
murmur set runtime-role <name> < runtime-role.yaml
murmur rm runtime-role <name>
murmur runtime-role <slug> [name]
```

Manage this resource with [`murmur get`](https://docs.murmur.dev/cli/get), [`murmur set`](https://docs.murmur.dev/cli/set), and [`murmur rm`](https://docs.murmur.dev/cli/rm).

## Builtin runtime roles

| Role | What the agent may do |
| - | - |
| `murmur-agent` | The default. Create, read, edit, and delete itself and its descendants; read and use its workspace; read the workspace's recipes, images, environments, personas, canned responses, knowledge, tool-link policies, and secret metadata; manage knowledge in its workspace; read machine types and runtime roles; create attachments; create, read, and endorse change requests. |
| `murmur-director` | Everything its owner may do within the agent's current [workspace](https://docs.murmur.dev/concepts/workspaces.md), including managing other owners' agents there, plus the tenant-level reads above. The dashboard starts a new [director](https://docs.murmur.dev/concepts/director.md) with this role. |
| `murmur-unrestricted` | Everything its owner may do throughout the tenant, including administration. |

## Selecting a runtime role

* **At spawn.** Pass `--runtime-role <name>` to [`murmur spawn`](https://docs.murmur.dev/cli/spawn), or set `runtime_role_ref` in the API. Off a VM the default is `murmur-agent`. An agent spawned by another agent inherits its parent's current role.
* **On a flight.** Set `runtime_role_ref` on the [flight](https://docs.murmur.dev/catalog/flight.md). Agents it creates use that role. Omitted uses `murmur-agent`.
* **On a running agent.** Run `murmur runtime-role <slug> <name>`, or choose a role from **Permissions → Platform** in the dashboard. Only the agent's recorded owner may change it, and the change applies to the agent's next request. Run `murmur runtime-role <slug>` to print the current role.

Selecting a role requires `runtime-role.read` on it. Re-spawning an existing agent keeps its role and rejects a spawn that names a different one.

## Fields

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | string | yes | Unique runtime-role name. Names starting with `murmur-` are reserved for platform builtins. |
| `description` | string | no | Human-readable description. |
| `workspacePermissions` | object\[] | no | [Entries](#entry-fields) allowed within the agent's current workspace, including other owners' agents and resources shared into it. |
| `tenantPermissions` | object\[] | no | [Entries](#entry-fields) allowed throughout the tenant, including all workspaces. |

## Entry fields

Entries are alternatives: a request is allowed when any one entry matches it.

| Name | Type | Required | Description |
| - | - | - | - |
| `inline.permissions` | string\[] | one of | [Permission](https://docs.murmur.dev/security/permissions.md) strings this entry allows. |
| `role` | string | one of | A [role](https://docs.murmur.dev/catalog/role.md) whose current permissions this entry allows. |
| `namePattern` | string | no | Exact target name or trailing-`*` prefix, with [caller variables](https://docs.murmur.dev/security/authorization.md#name-patterns). `${slug}` is the agent's full relative path. Empty matches any target. |
| `description` | string | no | Plain-English explanation of the entry. Does not affect authorization. |

## Example

A custom role replaces `murmur-agent` rather than adding to it, so start from a copy of it. This role lets an agent manage its own subtree and read its workspace's knowledge, and nothing else:

```yaml theme={null}
name: subtree-and-knowledge
description: Manage this agent's subtree and read workspace knowledge.
workspacePermissions:
  - inline:
      permissions: [agent.create, agent.read, agent.edit, agent.delete]
    namePattern: "${owner_provider}/${owner_account}/w/${workspace}/${slug}"
  - inline:
      permissions: [agent.create, agent.read, agent.edit, agent.delete]
    namePattern: "${owner_provider}/${owner_account}/w/${workspace}/${slug}/*"
  - inline:
      permissions: [workspace.read, workspace.use]
    namePattern: "${workspace}"
  - inline:
      permissions: [knowledge.read]
```

```bash theme={null}
murmur set runtime-role subtree-and-knowledge < runtime-role.yaml
murmur runtime-role <slug> subtree-and-knowledge
```

## Related

* [github-role](https://docs.murmur.dev/catalog/github-role.md): what an agent may do on GitHub
* [Authorization](https://docs.murmur.dev/security/authorization.md)
* [Permission reference](https://docs.murmur.dev/security/permission-reference.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.