Drive permissions

Restrict which sandboxes, agents, or jobs can mount an Agent Drive using label-based ACL rules with read or read-write access and path scoping.

Drive permissions restrict which sandboxes, agents, or jobs can mount a specific drive. Permissions are evaluated against the workload’s identity labels at mount time. If no permissions are defined on a drive, any workload in the workspace can mount it.

How permissions work

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)

Permissions are evaluated with OR logic: the first matching rule grants access. Within a single rule, all specified labels must match (AND logic).

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

from blaxel.core import SandboxInstance

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 drive permission rules at mount time.

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

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

Update permissions on an existing drive

Permissions can be modified on a drive that is already in use. Updated permissions apply to new mount requests. Existing mounts are not affected until remounted.

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

from blaxel.core.drive import DriveInstance

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 sandboxes with team: "data-science" can mount 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 see files under /reports when it mounts the drive.

Behavior summary

Scenario	Result
No permissions defined on drive	Any workload in the workspace can mount
Permissions defined, workload labels match a rule	Mount allowed with the rule’s mode and path
Permissions defined, no rule matches	Mount denied
Multiple rules match	First matching rule applies
Rule with empty mode	Defaults to read-write
Rule with empty path	Defaults to / (full drive)

Permissions are enforced at mount time. If you update permissions on a drive, existing mounts are not affected. The workload must unmount and remount to pick up the new rules.

Agent Drive overview

Create, mount, and manage drives.

Sandboxes overview

Learn about sandbox lifecycle and configuration.