Skip to content

docs: add UID/GID mapping section to Agent Drive overview #582

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
devin-ai-integration wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add UID/GID mapping section to Agent Drive overview #582

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
95491fd
docs: add UID/GID mapping section to Agent Drive overview
Joffref May 28, 2026
affe4e8
docs: remove filer references from UID/GID mapping section
Joffref May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions Agent-drive/Overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,45 @@ Read-only mode is enforced at mount time, not at the storage/system level. There
To make the read-only guarantee effective in an adversarial/agentic setup, you should restrict the agent's access to `/var/run/secrets/blaxel.ai/identity/token`, and also block the `blfs` binary from the agent's `PATH` / execution scope.
</Warning>

### Map UID/GID on mount

When the sandbox process runs as a non-root user, files on the drive may appear inaccessible due to ownership mismatch. You can remap file ownership at mount time by specifying a local UID and/or GID.

<CodeGroup>

```tsx TypeScript
await sandbox.drives.mount({
driveName: "my-drive",
mountPath: "/mnt/data",
uidMap: "1000",
gidMap: "1000",
});
```

```python Python
await sandbox.drives.mount(
drive_name="my-drive",
mount_path="/mnt/data",
uid_map="1000",
gid_map="1000",
)
```

</CodeGroup>

With this configuration, drive files will appear as owned by UID/GID `1000` inside the sandbox. Both fields are optional and accept any non-negative integer.

#### Default mapping via environment variables

Set `BLFS_UID_MAP` and `BLFS_GID_MAP` on the sandbox to apply UID/GID mapping to every mount by default, without passing the values in each request.

| Variable | Description |
|---|---|
| `BLFS_UID_MAP` | Default local UID for drive file ownership mapping |
| `BLFS_GID_MAP` | Default local GID for drive file ownership mapping |

Per-request values override environment variable defaults. If neither is set, no mapping is applied and the mount behaves as before.

## List mounted drives

List all drives currently mounted to a sandbox:
Expand Down