> ## Documentation Index
> Fetch the complete documentation index at: https://blaxel-mendral-deps-weekly-safe-github-actions-20260803.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Drive permissions

> Configure label-based ACL rules on an Agent Drive to grant sandboxes, agents, or jobs read or read-write access, scoped to specific paths.

Drive permissions control which sandboxes, agents, or jobs can access the contents of a drive (or a specific folder in a drive). They are access control rules set at the drive level, evaluated against the workload's identity labels. If no permissions are defined on a drive, any workload in the workspace can access all of its contents.

## Mount and access are different things

The most common point of confusion is treating a mount as an access boundary. It is not. Mounting and accessing a drive are two separate operations, and permissions govern access, not the mount.

* Mounting is a client-side operation. It projects a drive's contents into a sandbox's filesystem at a mount path, so the workload can read and write files with a standard POSIX interface. Mounting a drive is like serving a website locally: it changes where the content appears, not who is allowed to reach it.
* Accessing is reaching the drive's contents. Agent Drive exposes an internal HTTP API, so a workload can read and write a drive's files directly, whether or not the drive is mounted anywhere.

Because a workload can reach a drive's contents through the API without ever mounting it, controlling the mount does not isolate a drive. Permissions are what isolate a drive: they are enforced by the server for every access path, both mounts and direct API calls.

<Warning>
  By default, a new drive has no permissions, which means any workload in the workspace can access all of its contents, mounted or not. Set permissions to restrict access to the workloads you choose.
</Warning>

## How permissions work

Permissions are a list of access control rules attached to a drive. A workload is granted access when it matches a rule, and the same rules apply whether the workload mounts the drive or calls the HTTP API directly.

Each drive can have up to 3 permission rules. A permission rule contains:

| Field    | Description                                                      | Default          |
| -------- | ---------------------------------------------------------------- | ---------------- |
| `labels` | Key-value pairs the workload must have (AND logic within a rule) | Required         |
| `mode`   | Access mode: `read` or `read-write`                              | `read-write`     |
| `path`   | Subfolder the workload is restricted to                          | `/` (full drive) |

Rules are evaluated with OR logic: the first matching rule grants access with its `mode` and `path`. Within a single rule, all specified labels must match (AND logic). If no rule matches, access is denied.

## Label matching

Workload labels are automatically injected into the workload's identity token at creation time. These include infrastructure labels (like `blaxel-workspace`, `blaxel-type`, `blaxel-name`) and any user-defined labels set on the resource's metadata.

To add user-defined labels to a sandbox, set them in `labels` when creating the resource:

<CodeGroup>
  ```tsx TypeScript theme={null}
  import { SandboxInstance } from "@blaxel/core";

  const sandbox = await SandboxInstance.create({
    name: "my-sandbox",
    image: "my-image",
    labels: { team: "backend", env: "production" },
  });
  ```

  ```python Python theme={null}
  from blaxel.core import SandboxInstance

  sandbox = await SandboxInstance.create(
      {
          "name": "my-sandbox",
          "image": "my-image",
          "labels": {"team": "backend", "env": "production"},
      }
  )
  ```
</CodeGroup>

These labels then appear in the workload identity token and are evaluated against the drive's permission rules on every access.

## Create a drive with permissions

<CodeGroup>
  ```tsx TypeScript theme={null}
  import { DriveInstance } from "@blaxel/core";

  const drive = await DriveInstance.create({
    name: "team-drive",
    region: "us-was-1",
    permissions: [
      {
        labels: { team: "backend" },
        mode: "read-write",
      },
      {
        labels: { team: "frontend" },
        mode: "read",
        path: "/shared",
      },
    ],
  });
  ```

  ```python Python theme={null}
  from blaxel.core.drive import DriveInstance

  drive = await DriveInstance.create(
      {
          "name": "team-drive",
          "region": "us-was-1",
          "permissions": [
              {
                  "labels": {"team": "backend"},
                  "mode": "read-write",
              },
              {
                  "labels": {"team": "frontend"},
                  "mode": "read",
                  "path": "/shared",
              },
          ],
      }
  )
  ```
</CodeGroup>

## Update permissions on an existing drive

Permissions can be modified on a drive that is already in use.

<CodeGroup>
  ```tsx TypeScript theme={null}
  import { DriveInstance } from "@blaxel/core";

  const drive = await DriveInstance.get("team-drive");
  await drive.update({
    permissions: [
      {
        labels: { team: "backend", env: "production" },
        mode: "read-write",
      },
    ],
  });
  ```

  ```python Python theme={null}
  from blaxel.core.drive import DriveInstance

  drive = await DriveInstance.get("team-drive")
  await drive.update(
      {
          "permissions": [
              {
                  "labels": {"team": "backend", "env": "production"},
                  "mode": "read-write",
              },
          ],
      }
  )
  ```
</CodeGroup>

To remove all permissions and make the drive open-access again, set `permissions` to an empty array.

## Permission patterns

### Restrict to a single team

Only workloads with `team: "data-science"` can access the drive:

```tsx TypeScript theme={null}
permissions: [
  { labels: { team: "data-science" }, mode: "read-write" },
]
```

### AND logic (multiple labels in one rule)

The workload must have both `team: "backend"` AND `env: "production"` to match:

```tsx TypeScript theme={null}
permissions: [
  { labels: { team: "backend", env: "production" }, mode: "read-write" },
]
```

### OR logic (multiple rules)

Either `team: "backend"` OR `team: "ml"` can access the drive:

```tsx TypeScript theme={null}
permissions: [
  { labels: { team: "backend" }, mode: "read-write" },
  { labels: { team: "ml" }, mode: "read-write" },
]
```

### Read-only access for some teams

The backend team gets full access, the frontend team can only read:

```tsx TypeScript theme={null}
permissions: [
  { labels: { team: "backend" }, mode: "read-write" },
  { labels: { team: "frontend" }, mode: "read" },
]
```

### Path scoping

Restrict a workload to a specific subfolder within the drive:

```tsx TypeScript theme={null}
permissions: [
  { labels: { team: "analytics" }, mode: "read", path: "/reports" },
]
```

The workload can only access files under `/reports`, whether it reads them through the API or mounts the drive.

## Behavior summary

| Scenario                                          | Result                                                                            |
| ------------------------------------------------- | --------------------------------------------------------------------------------- |
| No permissions defined on drive                   | Any workload in the workspace can access all contents (via mount or internal API) |
| Permissions defined, workload labels match a rule | Access allowed with the rule's mode and path                                      |
| Permissions defined, no rule matches              | Access denied                                                                     |
| Multiple rules match                              | First matching rule applies                                                       |
| Rule with empty `mode`                            | Defaults to `read-write`                                                          |
| Rule with empty `path`                            | Defaults to `/` (full drive)                                                      |

<CardGroup cols={2}>
  <Card title="Agent Drive overview" href="/Agent-drive/Overview">
    Create, mount, and manage drives.
  </Card>

  <Card title="Sandboxes overview" href="/Sandboxes/Overview">
    Learn about sandbox lifecycle and configuration.
  </Card>
</CardGroup>