> ## 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. # Agent Access > Choose who may see and direct an agent: Shared, Selected people, or Private. Anyone who may use an agent can act with its roles through it. An [agent's](https://docs.murmur.dev/concepts/agents.md) **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. | Option | Who may use the agent | | - | - | | **Shared** | Collaborators in the [workspace](https://docs.murmur.dev/concepts/workspaces.md): its [Multi Player Collaborators and Administrators](https://docs.murmur.dev/catalog/workspace.md#access-grants). New top-level agents start here. | | **Selected people…** | Only the people and [groups](https://docs.murmur.dev/catalog/group.md) named here. | | **Private** | Nobody besides the owner. Administrators of the workspace can still see, stop, and purge it. | Whatever you choose, the owner, the VMs of the agent and the agents above it, and [tenant admins](https://docs.murmur.dev/security/permissions.md) 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](https://docs.murmur.dev/catalog/workspace.md#access-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](https://docs.murmur.dev/concepts/workspaces.md) never confers `agent.use`, even through a custom [role](https://docs.murmur.dev/catalog/role.md) 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. | Your role in the agent's workspace | Shared | Private | | - | - | - | | Single Player User | nothing | nothing | | Multi Player Collaborator | see, direct, stop | nothing | | Administrator | see, direct, stop, purge | see, stop, purge | | Owner, tenant admin | everything | everything | An agent you may not see does not appear in [listings](https://docs.murmur.dev/cli/ls.md), tree views, or [run history](https://docs.murmur.dev/cli/history.md). A refused request fails with `permission "agent.edit" denied: permission "agent.use" denied on agent …` (naming the permission requested), and [`murmur check-permissions`](https://docs.murmur.dev/cli/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`](https://docs.murmur.dev/cli/spawn) 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: | Agent | Who can change Access | | - | - | | A person's agent | Its owner, including when the agent runs with a service profile's credentials. | | A [service profile's](https://docs.murmur.dev/concepts/service-profiles.md) agent | Administrators of that agent's [workspace](https://docs.murmur.dev/concepts/workspaces.md) (`workspace.administer`). | | Any agent | Tenant admins. | An agent can change Access only when its [runtime role](https://docs.murmur.dev/catalog/runtime-role.md) 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`](https://docs.murmur.dev/cli/set) on the [agent resource](https://docs.murmur.dev/catalog/agent.md). ## 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](https://docs.murmur.dev/catalog/runtime-role.md) and [GitHub role](https://docs.murmur.dev/catalog/github-role.md) 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](#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](https://docs.murmur.dev/concepts/director.md), 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](#github-steering)). Agents started with [`murmur spawn`](https://docs.murmur.dev/cli/spawn) or the [MCP server](https://docs.murmur.dev/mcp-server/overview.md) start as **Shared** whatever their role; run `murmur access me` to make one Private. ## Built-in roles | Role | Permissions | Purpose | | - | - | - | | `murmur-agent-owner` | `agent.use`, `agent.administer` | Held by the owner of a person's agent: use the agent tree and change its Access. | | `murmur-agent-collaborator` | `agent.use` | The role the Access setting grants to the people it names. | 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](https://docs.murmur.dev/catalog/steering-policy.md) 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](#sharing-an-agent-with-a-broad-role)). If you cannot change the setting, the row is disabled and says who can. ## CLI ```bash theme={null} murmur access [flags] [collaborators|me|selected --user LOGIN --group GROUP] ``` | Mode | Effect | | - | - | | *(none)* | Print the setting in force. | | `collaborators` | **Shared**: collaborators in the workspace. | | `me` | **Private**: only you; for a service profile's agent, only the profile. | | `selected` | Only the people and groups named by `--user` and `--group`. Requires at least one. | | Flag | Description | | - | - | | `--user` | Login allowed to use the agent with `selected`. Repeatable. | | `--group` | [Group](https://docs.murmur.dev/catalog/group.md) allowed to use the agent with `selected`. Repeatable. | | `--workspace` | [Workspace](https://docs.murmur.dev/concepts/workspaces.md) name, overriding `murmur.yaml`. | | `--json` | Print the setting as JSON. | `--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. ```bash theme={null} # Restrict an agent to two people and the release team murmur access fix-auth selected --user alice --user bob --group release # Make it Shared again murmur access fix-auth collaborators ``` ## Related * [Authorization](https://docs.murmur.dev/security/authorization.md) * [Permission reference](https://docs.murmur.dev/security/permission-reference.md) * [Runtime roles](https://docs.murmur.dev/catalog/runtime-role.md) and [GitHub roles](https://docs.murmur.dev/catalog/github-role.md) * [Steering policies](https://docs.murmur.dev/catalog/steering-policy.md) * [Workspace grants](https://docs.murmur.dev/catalog/workspace.md#access-grants) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.