# Permissions and security

How access to a Buddy Sandbox is calculated from project roles, direct assignments, and groups - plus repository and artifact access, tokens, and IP whitelists.

By default, access to a Sandbox follows the user's role in the project. You can override that per Sandbox on its **Permissions** tab.

![Sandbox permissions](/docs/sandboxes/sandboxes-permissions.png.md)

The tab has three sections, each assigned independently:

| Section | What you assign |
| :--- | :--- |
| **Member** | Individual workspace members |
| **Agent** | [AI agents](/docs/sandboxes/ai-agents.md) - assigned separately from people |
| **Group** | Groups, plus the **Others** row that covers everyone not matched above |

Use the **+** button in a section to open its assignment screen, pick a role per row, and confirm with **Assign roles**.

![Assigning members to a Sandbox](/docs/sandboxes/sandboxes-assign-members.png.md)

## How access is calculated

For a given user or agent, Buddy resolves permissions in this order:

1. **Assigned directly to the Sandbox?** That assignment decides, and nothing else is considered.
2. **Otherwise, a member of groups assigned to the Sandbox?** The widest of those groups' permissions wins.
3. **Otherwise** - the level configured on the **Others** row applies.

Granting one person **Manage** role does not require touching group configuration, and removing someone from a group takes their access away immediately.

## Access levels

![The role selector on a Sandbox permission row](/docs/sandboxes/sandboxes-permission-roles.png.md)

| Level | What it allows | Value in YAML and the API |
| :--- | :--- | :--- |
| **Manage** | Full control - edit settings, delete the Sandbox, manage its permissions | `READ_WRITE` |
| **View-only** | See the Sandbox and its activity, nothing else | `READ_ONLY` |
| **Project role** | Inherit whatever the user's role in the project grants - the default | `DEFAULT` |
| **None (Deny)** | No access at all | `DENIED` |

<Hint type="info">

Users whose effective level is **Manage** can also open the Sandbox terminal and log in over SSH - the public keys from their Buddy profile are added to the machine automatically. See [Terminal and SSH](/docs/sandboxes/terminal-and-ssh.md).

</Hint>

Workspace owners and administrators always have **Manage** on every Sandbox, and this cannot be changed. Their rows show **Manage** greyed out, and a lower level written over the API is ignored for them - the effective access stays **Manage**.

## Sandbox access to repositories and artifacts

A Sandbox's access to your code is granted on the resource, not on the machine. Open the **Project repository** target or the artifact, go to its **Permissions** tab, and add a row in the **Sandbox** section - either a single Sandbox, or **All sandboxes** to cover every one of them at once.

| Role | What the Sandbox can do |
| :--- | :--- |
| **Read-only** | Fetch the repository. The default |
| **Read-write** | Fetch and push - what an [AI agent](/docs/sandboxes/ai-agents.md) needs to commit its work |
| **None (Deny)** | Nothing, even if **All sandboxes** grants access. The way to exclude one machine from a blanket rule |

With that in place, fetching and pushing need no credentials inside the Sandbox at all. See [Git and Artifacts](/docs/sandboxes/git-and-artifacts.md).

## Programmatic access

**Tokens scoped to Sandboxes.** Automation does not need a full personal access token. Issue a token limited to Sandbox operations.

**IP whitelist.** At workspace level you can restrict which addresses may reach the REST API and the CLI.

## Isolation

Each Sandbox is an isolated machine with its own filesystem, processes, and network. Code running in one Sandbox does not see another.

Inside a single Sandbox, standard Linux users are your isolation boundary: give each workload its own system user when you run several in parallel. See [Terminal and SSH](/docs/sandboxes/terminal-and-ssh.md).

## Who did what

Lifecycle operations and executed commands are recorded in the Sandbox activity view - see [Logs](/docs/sandboxes/logs.md).

Project-level roles, which Sandbox permissions build on, are described in [Roles and permissions](/docs/basics/collaboration/roles.md).

<Hint type="info">

Permissions can also be defined in the [Sandbox YAML](/docs/yaml/yaml-sandbox.md) and over the [REST API](/docs/api/sandboxes/edit.md).

</Hint>


---
Original source: https://buddy.works/docs/sandboxes/permissions-and-security