From e8060cc0e4b4ff43f8110ea38a9b682cfcd11d41 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 18 Jun 2026 08:47:32 +0200 Subject: [PATCH 1/3] docs: document sbx mount/umount for running sandboxes Add a usage section covering sbx mount and sbx umount, which expose host paths into an already-running sandbox at runtime using a docker run -v style spec (HOST[:CONTAINER_TARGET[:ro|rw]]). Co-Authored-By: Claude Opus 4.8 (1M context) --- content/manuals/ai/sandboxes/usage.md | 48 +++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 0b4eb1c2d946..d00e8ceb3861 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -224,6 +224,54 @@ $ sbx run claude ~/project-b $ sbx rm # 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 follows the same +`HOST[:CONTAINER_TARGET[:ro|rw]]` form as `docker run -v`: + +```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 a +container target. The target must be an absolute path: + +```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 container target, +pass the same target back to also remove the bind mount inside the sandbox: + +```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 From eba81a182dec6147dc4f8227ccb96016cd23760d Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 18 Jun 2026 08:59:44 +0200 Subject: [PATCH 2/3] docs: clarify sbx mount path wording Co-Authored-By: Claude Opus 4.8 (1M context) --- content/manuals/ai/sandboxes/usage.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index d00e8ceb3861..a1c492acf598 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -228,8 +228,9 @@ $ sbx rm # when finished 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 follows the same -`HOST[:CONTAINER_TARGET[:ro|rw]]` form as `docker run -v`: +recreating it — use `sbx mount`. The mount spec takes a shape similar to +Docker's `-v` flag, `HOST[:PATH[:ro|rw]]`, where `PATH` is a location inside +the sandbox: ```console $ sbx mount my-sandbox /Users/me/extra-data @@ -239,8 +240,8 @@ 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 a -container target. The target must be an absolute path: +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 @@ -259,8 +260,8 @@ 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 container target, -pass the same target back to also remove the bind mount inside the sandbox: +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 From 0eb66040151fdf73b82259d70aaf9c5191d47550 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 18 Jun 2026 16:01:06 +0200 Subject: [PATCH 3/3] docs: name the sbx mount host path placeholder Co-Authored-By: Claude Opus 4.8 (1M context) --- content/manuals/ai/sandboxes/usage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index a1c492acf598..e04674ea6a5b 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -229,8 +229,8 @@ $ sbx rm # when finished 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[:ro|rw]]`, where `PATH` is a location inside -the sandbox: +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