From 53eb26d0132d214b4ffba4c5ff3b28bdb952cc6f Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 09:19:11 +0000 Subject: [PATCH 1/3] docs: explain mapped SMB workspaces and recovery Windows workspace guidance omits mapped SMB drives and recovery when a saved mapping disconnects. Document additional workspace support, retained mount sources, and recovery for dynamic and fixed workspaces. --- content/manuals/ai/sandboxes/troubleshooting.md | 13 +++++++++++++ content/manuals/ai/sandboxes/usage.md | 9 +++++++++ 2 files changed, 22 insertions(+) diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index d354114de74..a7c55c5bbcc 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -143,6 +143,19 @@ Changing a host symlink to point elsewhere doesn't move an existing static mount. The sandbox retains the original source, and filesystem policy checks when you reuse the sandbox include that source. +On Windows, an additional workspace on a mapped SMB drive retains its +original UNC source and mapped path for filesystem policy checks. The saved +mapped path must remain available when the sandbox restarts, even if the UNC +source is still reachable. Restore a disconnected drive mapping before +retrying. Remapping the drive doesn't redirect the saved mount to another +share. + +To change the mapped path for a dynamically added mount, unmount it with +`sbx umount` and add it again with `sbx mount`. You can remove a saved dynamic +mount using its recorded mapped path and sandbox target even if the drive is +disconnected. For a workspace fixed at creation, restore the mapping or remove +and recreate the sandbox. + ## Kiro, Copilot, or Droid shorthand fails In Docker Sandboxes v0.42, `sbx run kiro`, `sbx run copilot`, and diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 94b0f948406..fa3e71e36f4 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -406,6 +406,15 @@ 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`. +On Windows with the `docker-next` backend, additional workspaces can use +mapped SMB drives, such as `Z:\shared`, or UNC paths, such as +`\\server\share\shared`. The mount uses the UNC source while keeping the +requested sandbox target and read-only setting. Filesystem policy checks +include both the mapped path and the UNC source. This support is limited to +additional workspaces and doesn't cover the experimental Runtime backend. +Keep the saved drive mapping available when restarting the sandbox; see +[mapped-drive recovery](troubleshooting.md#sandbox-reports-a-mount-state-error). + You can also run separate projects side-by-side. Remove unused sandboxes when you're done to reclaim disk space: From a37a83bb7633879c2772eb2f6934eeaf74526b08 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 09:57:59 +0000 Subject: [PATCH 2/3] docs: revise mapped-drive recovery guidance The recovery guidance included hidden mount commands. Explain how to recreate a sandbox with an updated workspace path and preserve files before removal. --- content/manuals/ai/sandboxes/troubleshooting.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index a7c55c5bbcc..9f972d063ee 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -150,11 +150,10 @@ source is still reachable. Restore a disconnected drive mapping before retrying. Remapping the drive doesn't redirect the saved mount to another share. -To change the mapped path for a dynamically added mount, unmount it with -`sbx umount` and add it again with `sbx mount`. You can remove a saved dynamic -mount using its recorded mapped path and sandbox target even if the drive is -disconnected. For a workspace fixed at creation, restore the mapping or remove -and recreate the sandbox. +To use a different mapped path, remove and recreate the sandbox with the +updated workspace path. Before removing the sandbox, +[copy out any files you want to keep](usage.md#copy-files-between-host-and-sandbox) +if it's still accessible. Removing a sandbox deletes its sandbox data. ## Kiro, Copilot, or Droid shorthand fails From b74afe31d52dc4f2200d5a7e4eeaa1ed7f95c9d5 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 12:13:47 +0000 Subject: [PATCH 3/3] docs: focus mapped drive guidance on restart recovery Mapped drive details interrupted the general workspace instructions and exposed backend terminology. Keep concise recovery guidance in a dedicated troubleshooting section. --- content/manuals/ai/sandboxes/troubleshooting.md | 13 +++++++------ content/manuals/ai/sandboxes/usage.md | 9 --------- 2 files changed, 7 insertions(+), 15 deletions(-) diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 9f972d063ee..3145869c251 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -143,12 +143,13 @@ Changing a host symlink to point elsewhere doesn't move an existing static mount. The sandbox retains the original source, and filesystem policy checks when you reuse the sandbox include that source. -On Windows, an additional workspace on a mapped SMB drive retains its -original UNC source and mapped path for filesystem policy checks. The saved -mapped path must remain available when the sandbox restarts, even if the UNC -source is still reachable. Restore a disconnected drive mapping before -retrying. Remapping the drive doesn't redirect the saved mount to another -share. +## Sandbox won't restart after a drive disconnects + +If an additional workspace uses a mapped SMB drive on Windows, restore the +original drive mapping before restarting the sandbox. The saved mapped path +must remain available for filesystem policy checks, even if the network share +is still reachable. Remapping the drive doesn't change the saved workspace +source. To use a different mapped path, remove and recreate the sandbox with the updated workspace path. Before removing the sandbox, diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index fa3e71e36f4..94b0f948406 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -406,15 +406,6 @@ 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`. -On Windows with the `docker-next` backend, additional workspaces can use -mapped SMB drives, such as `Z:\shared`, or UNC paths, such as -`\\server\share\shared`. The mount uses the UNC source while keeping the -requested sandbox target and read-only setting. Filesystem policy checks -include both the mapped path and the UNC source. This support is limited to -additional workspaces and doesn't cover the experimental Runtime backend. -Keep the saved drive mapping available when restarting the sandbox; see -[mapped-drive recovery](troubleshooting.md#sandbox-reports-a-mount-state-error). - You can also run separate projects side-by-side. Remove unused sandboxes when you're done to reclaim disk space: