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.

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.

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:

TypeScript

import { SandboxInstance } from "@blaxel/core";

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

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

TypeScript

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",
    },
  ],
});

Update permissions on an existing drive

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

TypeScript

import { DriveInstance } from "@blaxel/core";

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

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:

TypeScript

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:

TypeScript

permissions: [
  { labels: { team: "backend", env: "production" }, mode: "read-write" },
]

OR logic (multiple rules)

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

TypeScript

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:

TypeScript

permissions: [
  { labels: { team: "backend" }, mode: "read-write" },
  { labels: { team: "frontend" }, mode: "read" },
]

Path scoping

Restrict a workload to a specific subfolder within the drive:

TypeScript

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)

Agent Drive overview

Create, mount, and manage drives.

Sandboxes overview

Learn about sandbox lifecycle and configuration.