Skip to content
Draft
Changes from all commits
Commits
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
49 changes: 49 additions & 0 deletions content/manuals/ai/sandboxes/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -224,6 +224,55 @@ $ sbx run claude ~/project-b
$ sbx rm <sandbox-name> # when finished
```

## Mounting host paths into a running sandbox

Extra workspaces passed to `sbx run` are fixed at create time. To expose an
additional host path to a sandbox that's already running — without stopping or
recreating it — use `sbx mount`. The mount spec takes a shape similar to
Docker's `-v` flag, `HOST_PATH[:PATH[:ro|rw]]`, where `HOST_PATH` is the path
on your machine and `PATH` is a location inside the sandbox:

```console
$ sbx mount my-sandbox /Users/me/extra-data
```

With a host path alone, the directory becomes visible inside the sandbox under
`/mnt/host/`, mirroring the host path — in this example,
`/mnt/host/Users/me/extra-data`.

To bind the host path to a specific location inside the sandbox, append that
path. It must be absolute:

```console
$ sbx mount my-sandbox /Users/me/extra-data:/workspace/data
```

Mounts are read-write by default. Append `:ro` to mount read-only — writes from
inside the sandbox then fail with a "read-only file system" error:

```console
$ sbx mount my-sandbox /Users/me/extra-data:/workspace/data:ro
```

The host path must exist. Relative host paths are resolved against your current
directory before being sent to the sandbox. Mount operations are idempotent, so
re-running the same command is a no-op. The same
[filesystem rules](governance/concepts.md#filesystem-rules) that govern
create-time mounts are enforced here, so a path your policy denies is rejected.

To revoke a path, use `sbx umount`. If you bound the path to a location inside
the sandbox, pass that same path back to also remove the bind mount:

```console
$ sbx umount my-sandbox /Users/me/extra-data # drop the host path
$ sbx umount my-sandbox /Users/me/extra-data:/workspace/data # also remove the bind mount
```

A host path with no target revokes only the exposed path. Like `sbx mount`,
`sbx umount` is idempotent — revoking a path that was never mounted succeeds
without error. Both commands operate on the live container, so the sandbox must
be running.

## Copying files between host and sandbox

Use [`sbx cp`](/reference/cli/sbx/cp/) to copy files or directories between
Expand Down