runtime-role catalog resource

A runtime role bounds the Murmur API calls an agent 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:

the agent’s runtime role, and
its recorded owner’s current permissions.

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

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, murmur set, and murmur 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, including managing other owners’ agents there, plus the tenant-level reads above. The dashboard starts a new director 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, 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. 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 allowed within the agent’s current workspace, including other owners’ agents and resources shared into it.
`tenantPermissions`	object[]	no	Entries 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 strings this entry allows.
`role`	string	one of	A role whose current permissions this entry allows.
`namePattern`	string	no	Exact target name or trailing-`*` prefix, with caller variables. `${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:

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]

murmur set runtime-role subtree-and-knowledge < runtime-role.yaml
murmur runtime-role <slug> subtree-and-knowledge

github-role: what an agent may do on GitHub
Authorization
Permission reference

Getting started

Core concepts

Integrations

Guides

runtime-role catalog resource

Synopsis

Builtin runtime roles

Selecting a runtime role

Fields

Entry fields

Example

​Synopsis

​Builtin runtime roles

​Selecting a runtime role

​Fields

​Entry fields

​Example

​Related

Synopsis

Builtin runtime roles

Selecting a runtime role

Fields

Entry fields

Example

Related