Skip to main content
An agent’s Access setting decides who may see it, direct it, and stop it. Directing an agent includes sending it follow-ups, waking it or putting it to sleep, opening SSH or port-forward sessions to its VM, updating its tasks, and starting agents under it. The setting belongs to the top-level agent and covers every agent below it. Whatever you choose, the owner, the VMs of the agent and the agents above it, and tenant admins can always use it.

​
How Access combines with other permissions

Access is the agent.use permission, and every action on an existing agent requires it beside the action’s own permission: seeing it (agent.read), directing it (agent.edit), stopping it (agent.delete), purging it (agent.purge), and changing its Access (agent.administer). Workspace grants and other grants confer those permissions as usual. Access only narrows: naming someone gives them agent.use, but they still need the action’s own permission. A grant on a workspace never confers agent.use, even through a custom role that includes * or agent.*. One exception keeps every agent accountable to its workspace: administrators of the agent’s workspace (workspace.administer) can always see, stop, and purge it, whatever its Access. They cannot direct it unless its Access admits them. An agent you may not see does not appear in listings, tree views, or run history. A refused request fails with permission "agent.edit" denied: permission "agent.use" denied on agent … (naming the permission requested), and murmur check-permissions reports that permission as denied on the agent. Spawning a new top-level agent does not require agent.use. Spawning under an existing agent requires agent.use on the nearest existing agent above the new one, because a child inherits its parent’s service profile, secrets, and repository restriction. Replacing an agent with --force-new or --resurrect requires agent.use on the agent it replaces, and the replacement keeps its Access setting.

​
Who can change Access

Exactly one party controls each agent’s Access, determined by who owns it: An agent can change Access only when its runtime role grants agent.administer (for a service profile’s agent, workspace.administer), and never beyond what its owner holds; the default murmur-agent role does not. Starting a service profile’s agent, holding service-profile.assume on the profile, and being the profile itself do not let you change its Access. Controlling Access does not by itself let you use the agent: a workspace administrator who wants to direct a service profile’s agent names themselves in its setting. The same rule applies to any write that changes who may use the agent, including murmur set on the agent resource.

​
Sharing an agent with a broad role

Anyone who may use an agent can act with its roles through it. The agent’s runtime role and GitHub role decide what it may do; its Access setting decides who may ask it to in Murmur, and its steering policy decides who may from GitHub (see GitHub steering). If you share an agent that can merge pull requests, everyone you share it with can get pull requests merged through it. The dashboard treats a role as broad when it reaches beyond the agent’s own work:
  • A runtime role is broad when it lets the agent manage other agents or administer access outside its own tree. murmur-director and murmur-unrestricted are broad; the default murmur-agent is not.
  • A GitHub role is broad when it can merge or approve pull requests, or write to every resource or to repository and organization settings. murmur-unrestricted is broad; murmur-coding-agent and murmur-read-only are not.
A custom role is judged by what it grants, the same way. While an agent with a broad role is Shared or shared with Selected people…, the agent’s Permissions panel tags that role Shared. Rest on or tap the tag to see who the role is shared with. To stop sharing it, set Access to Private. The dashboard also starts its own broad agents as Private:
  • A new workspace director, which runs murmur-director.
  • A new agent started from the spawn form with a broad runtime role, unless you choose Shared.
The spawn form shows the Access choice for every new agent. It defaults to Private for a broad runtime role and to Shared otherwise. The agent is created with the setting chosen, so it is never shared in between. A new director is also created with the steering policy murmur-owner-only-steering-policy, whatever its Access setting, so only you can steer it from GitHub (see GitHub steering). Agents started with murmur spawn or the MCP server start as Shared whatever their role; run murmur access <slug> me to make one Private.

​
Built-in roles

The owner is named by their account, not their login, so someone who later takes over a renamed login does not inherit access to the agent.

​
GitHub steering

The Access setting does not decide who steers an agent from GitHub events, such as pull request comments and reviews. Its steering policy does, whatever the Access setting is. An agent that is Private can still be steered by anyone its steering policy admits. To keep the two in step, set the agent’s steering policy to murmur-owner-only-steering-policy, which admits only the agent’s owner. Choose it in the GitHub row under Access in the agent’s Permissions panel.

​
Dashboard

Open an agent’s Permissions panel. Its Access section has two rows: GitHub, the agent’s steering policy, and Murmur, the Access setting. In the Murmur row, choose Shared, Selected people…, or Private. Selected people… shows the people and groups it names, with a field to add more. While the agent is shared and runs a broad role, the role is tagged Shared (see Sharing an agent with a broad role). If you cannot change the setting, the row is disabled and says who can.

​
CLI

--user and --group are accepted only with selected, which replaces the named list. The command prints the resulting setting and notes when you cannot change it.