From f4ccc5476ec3e11c3a2104eab575edea2552de1e Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 09:22:45 +0000 Subject: [PATCH 1/4] docs: explain stop or force requirements for sandbox removal Removal guidance omitted the running sandbox safeguard. Explain stopping first or forcing removal, bulk command failures, and environment refusal before approval or cleanup. --- .../ai/sandboxes/configuration/environment-files.md | 5 +++++ content/manuals/ai/sandboxes/usage.md | 13 ++++++++++--- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md index b4d8b78d88e..3d8b7a6ceb7 100644 --- a/content/manuals/ai/sandboxes/configuration/environment-files.md +++ b/content/manuals/ai/sandboxes/configuration/environment-files.md @@ -662,6 +662,11 @@ remote MCP server registrations are host-global and can be shared by multiple sandboxes. Local MCP commands declared by the environment belong to that environment and sandbox. +For a local environment, stop its sandbox with `sbx stop ` before +running `sbx env rm`. If the sandbox is running, removal is refused before +plan approval or cleanup. To remove it while running and skip approval, use +`sbx env rm --force`. + `sbx env rm` builds a destroy plan from the resources on the host. The plan includes all credentials stored at the sandbox's scope, including credentials that the environment file no longer declares. After approval, `sbx` removes diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 94b0f948406..dcc6b40a90c 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -38,14 +38,21 @@ $ sbx stop my-sandbox # pause it $ sbx rm my-sandbox # delete it entirely ``` -`sbx rm` asks for confirmation before deleting a sandbox. Use `--force` to -skip the prompt. This flag also permits removal when the sandbox has an active -session — an open attach, SSH connection, or in-flight SFTP transfer: +`sbx rm` refuses to remove a running sandbox, even when no session is +connected. Stop it with `sbx stop` before removing it. To delete a running +sandbox, use `--force`. This flag also skips confirmation and permits removal +when the sandbox has an active session — an open attach, SSH connection, or +in-flight SFTP transfer: ```console $ sbx rm --force my-sandbox ``` +When you specify multiple names or use `sbx rm --all` without `--force`, +`sbx rm` asks for confirmation once. After confirmation, running sandboxes are +left in place with an error, and the command continues removing the other +sandboxes. If any removal fails, the command exits with status 1. + If you need a clean slate, remove the sandbox and run it again: ```console From a78c6fac547dd8c3439727192f0fc234dabe9607 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 10:03:13 +0000 Subject: [PATCH 2/4] docs: Separate sandbox recreation from bulk removal Bulk removal guidance interrupted the transition to recreating a sandbox. Give recreation its own subsection and group multi-target removal with pruning. --- content/manuals/ai/sandboxes/usage.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index dcc6b40a90c..cbb5f411851 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -48,10 +48,7 @@ in-flight SFTP transfer: $ sbx rm --force my-sandbox ``` -When you specify multiple names or use `sbx rm --all` without `--force`, -`sbx rm` asks for confirmation once. After confirmation, running sandboxes are -left in place with an error, and the command continues removing the other -sandboxes. If any removal fails, the command exits with status 1. +### Recreate a sandbox If you need a clean slate, remove the sandbox and run it again: @@ -61,6 +58,13 @@ $ sbx rm my-sandbox $ sbx run claude ``` +### Remove multiple sandboxes + +When you specify multiple names or use `sbx rm --all` without `--force`, +`sbx rm` asks for confirmation once. After confirmation, running sandboxes are +left in place with an error, and the command continues removing the other +sandboxes. If any removal fails, the command exits with status 1. + To remove all stopped local sandboxes, use `sbx prune`. Running sandboxes are never removed. Preview the sandboxes that would be removed, or filter out sandboxes stopped within the last week: From e6989e102c21d575217cb2587fafa325dccc0f52 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 10:14:18 +0000 Subject: [PATCH 3/4] docs: Lead bulk sandbox removal guidance with pruning Bulk removal guidance buried pruning behind details about partial failures. Show pruning first, then explain how to force removal of all sandboxes. --- content/manuals/ai/sandboxes/usage.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index cbb5f411851..ba7da493c23 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -39,14 +39,8 @@ $ sbx rm my-sandbox # delete it entirely ``` `sbx rm` refuses to remove a running sandbox, even when no session is -connected. Stop it with `sbx stop` before removing it. To delete a running -sandbox, use `--force`. This flag also skips confirmation and permits removal -when the sandbox has an active session — an open attach, SSH connection, or -in-flight SFTP transfer: - -```console -$ sbx rm --force my-sandbox -``` +connected. Stop it with `sbx stop` before removing it, or use `--force` to +delete it while it is running. ### Recreate a sandbox @@ -60,11 +54,6 @@ $ sbx run claude ### Remove multiple sandboxes -When you specify multiple names or use `sbx rm --all` without `--force`, -`sbx rm` asks for confirmation once. After confirmation, running sandboxes are -left in place with an error, and the command continues removing the other -sandboxes. If any removal fails, the command exits with status 1. - To remove all stopped local sandboxes, use `sbx prune`. Running sandboxes are never removed. Preview the sandboxes that would be removed, or filter out sandboxes stopped within the last week: @@ -80,6 +69,15 @@ such as `168h`, an RFC 3339 timestamp, or a Unix timestamp. The older Run `sbx prune` without flags to confirm and remove all stopped sandboxes. +To remove all local sandboxes, including running ones, use `sbx rm --all +--force`. The `--force` flag skips confirmation and permits removal even when +a sandbox has an active session — an open attach, SSH connection, or in-flight +SFTP transfer: + +```console +$ sbx rm --all --force +``` + ### Remove a sandbox when the agent exits Pass `--rm` to `sbx run` for a throwaway session. The sandbox is removed when From 5f5ae72c8afbd1786d49829f3603751c56625c4d Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 16:31:24 +0000 Subject: [PATCH 4/4] docs: simplify sandbox removal and recovery guidance Keep confirmation and stop-or-force behavior together, remove unnecessary session distinctions, and stop the sandbox before the recovery example removes it. --- content/manuals/ai/sandboxes/troubleshooting.md | 1 + content/manuals/ai/sandboxes/usage.md | 11 ++++------- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index d354114de74..b4081c6df52 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -120,6 +120,7 @@ reuse the name of an existing mountless sandbox, first then remove and recreate it with a workspace path: ```console +$ sbx stop $ sbx rm $ sbx run --name ``` diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index ba7da493c23..d6743bb5a2d 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -38,9 +38,9 @@ $ sbx stop my-sandbox # pause it $ sbx rm my-sandbox # delete it entirely ``` -`sbx rm` refuses to remove a running sandbox, even when no session is -connected. Stop it with `sbx stop` before removing it, or use `--force` to -delete it while it is running. +`sbx rm` asks for confirmation and requires the sandbox to be stopped. Use +`sbx stop` first, or use `--force` to skip confirmation and remove a running +sandbox. ### Recreate a sandbox @@ -69,10 +69,7 @@ such as `168h`, an RFC 3339 timestamp, or a Unix timestamp. The older Run `sbx prune` without flags to confirm and remove all stopped sandboxes. -To remove all local sandboxes, including running ones, use `sbx rm --all ---force`. The `--force` flag skips confirmation and permits removal even when -a sandbox has an active session — an open attach, SSH connection, or in-flight -SFTP transfer: +To remove all local sandboxes, including running ones, and skip confirmation: ```console $ sbx rm --all --force