From 206d120f2ab19871510341c36f73ae78ffcfa407 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 4 Nov 2026 10:02:55 +0100 Subject: [PATCH] Document custom mount targets for additional sandbox workspaces (#26476) Document how to mount additional sandbox workspaces at a chosen path with the CLI or an environment file. Include target restrictions and clarify that mounting at the host path remains the default. Validation: Formatting and scoped Markdown and Vale checks pass for all four changed pages. CLI examples were not run because `sbx` was unavailable. --- content/manuals/ai/sandboxes/architecture.md | 11 +++++---- .../configuration/environment-files.md | 23 +++++++++++++++---- .../ai/sandboxes/integrations/_index.md | 12 ++++++---- content/manuals/ai/sandboxes/usage.md | 20 ++++++++++++++-- 4 files changed, 50 insertions(+), 16 deletions(-) diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index b0fbbb904b..cd6f93b913 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -27,11 +27,12 @@ current directory when you don't pass a path. The sandbox sees your actual host files, so changes in either direction are instant with no sync process involved. -A directly mounted workspace appears at the same absolute path as on your -host. Preserving absolute paths means error messages, configuration files, and -build outputs all reference paths you can find on your host. The agent sees the -same directory structure, which reduces confusion when debugging or reviewing -changes. +By default, a directly mounted workspace appears at the same absolute path as +on your host. Preserving absolute paths means error messages, configuration +files, and build outputs all reference paths you can find on your host. The +agent sees the same directory structure, which reduces confusion when debugging +or reviewing changes. You can choose a different sandbox path for +[additional workspaces](usage.md#multiple-workspaces). Clone mode uses a third storage layout. The host repository is mounted read-only at `/run/sandbox/source`, and the agent works in a private clone diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md index 55bbb2579b..6137d3fa66 100644 --- a/content/manuals/ai/sandboxes/configuration/environment-files.md +++ b/content/manuals/ai/sandboxes/configuration/environment-files.md @@ -688,10 +688,25 @@ You can override `workspace.clone` for one `create` or `run` invocation with Each additional workspace is mounted after the primary workspace. Relative paths resolve from the directory of the environment file that declares them. -| Field | Type | Required | Default | Description | -| ---------- | ------- | -------- | ------- | ----------------------------- | -| `path` | string | Yes | None | Directory to mount | -| `readOnly` | boolean | No | `false` | Mount the directory read-only | +| Field | Type | Required | Default | Description | +| ---------- | ------- | -------- | ---------------------------- | -------------------------------------- | +| `path` | string | Yes | None | Directory to mount | +| `target` | string | No | Host path inside the sandbox | Absolute POSIX path inside the sandbox | +| `readOnly` | boolean | No | `false` | Mount the directory read-only | + +For example, mount a shared library directory read-only at a chosen path: + +```yaml +workspace: . +additionalWorkspaces: + - path: ../shared-libs + target: /workspace/libs + readOnly: true +``` + +Omit `target` to use the host path inside the sandbox. The same +[target restrictions](../usage.md#multiple-workspaces) apply as with +`sbx create` and `sbx run`. ### `mounts` diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md index 86624b79a9..545bc939e7 100644 --- a/content/manuals/ai/sandboxes/integrations/_index.md +++ b/content/manuals/ai/sandboxes/integrations/_index.md @@ -125,11 +125,13 @@ client. An interactive SSH shell starts in the sandbox workspace, matching home directory, `/home/agent`. Select the intended folder explicitly in the editor instead of relying on its initial location. -For a sandbox with a primary workspace, each workspace path appears inside the -sandbox at the same absolute path as on the host. For example, if you pass -`/Users/bob/src/my-project`, select that path in the remote folder picker. For -a mountless sandbox that uses a Docker-provided agent template, select -`/home/agent/workspace`. +In the remote folder picker, select the workspace's path inside the sandbox. +A workspace mounted from `/Users/bob/src/my-project` uses that same path by +default. A custom mount target such as `/workspace/data` is the path to open +in the editor. + +Docker-provided agent templates use `/home/agent/workspace` as the workspace +folder for mountless sandboxes. ## Connect a specific tool diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 1f1a616b43..f21db43dd8 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -347,14 +347,30 @@ The first path is the primary workspace — the agent starts here, and the sandbox's in-container Git clone is populated from this directory if you use `--clone`. Extra workspaces are always mounted directly. -Each workspace path appears inside the sandbox at the same absolute path as on -the host. Append `:ro` to mount an extra workspace read-only — useful for +By default, each directly mounted workspace appears at the same absolute path +as on the host. Append `:ro` to mount an extra workspace read-only — useful for reference material or shared libraries the agent shouldn't modify: ```console $ sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro ``` +To choose a sandbox path for an additional workspace, use +`PATH:TARGET[:ro]` with `sbx run` or `sbx create`: + +```console +$ sbx run claude ~/project-a ~/shared-libs:/workspace/libs:ro +``` + +This mounts `~/shared-libs` read-only at `/workspace/libs` inside the sandbox. +The primary workspace doesn't accept a target. + +The target must be an absolute POSIX path other than `/`, without colons or +NUL bytes. Choose a distinct target for each additional workspace. Targets +must not match the primary workspace path or a reserved skills path. In clone +mode, they must also stay outside the clone directory and must not match +`/run/sandbox/source`. + You can also run separate projects side-by-side. Remove unused sandboxes when you're done to reclaim disk space: