From 777a8a3a415ec1fb3f65f004f3175481dcdcffa5 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Fri, 2 Oct 2026 11:10:07 +0200
Subject: [PATCH] sbx: document sbx run --rm

Explain that --rm removes a local or cloud sandbox when the agent
session exits, when a reattached sandbox is kept, and why --rm can't be
combined with --detached or --detach-keys.

Source: docker/sandboxes#6601

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/manuals/ai/sandboxes/cloud/usage.md | 14 ++++++++++++++
 content/manuals/ai/sandboxes/usage.md       | 17 +++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/content/manuals/ai/sandboxes/cloud/usage.md b/content/manuals/ai/sandboxes/cloud/usage.md
index 2eafc97acb..6f5da08f64 100644
--- a/content/manuals/ai/sandboxes/cloud/usage.md
+++ b/content/manuals/ai/sandboxes/cloud/usage.md
@@ -241,6 +241,20 @@ $ sbx --cloud rm cloud-project
 Removal asks for confirmation, deletes the cloud sandbox, and can't be undone.
 Use `--force` to skip the prompt in scripts.
 
+### Remove a sandbox when the agent exits
+
+Pass `--rm` to an interactive `run` to remove the sandbox when the agent
+session ends:
+
+```console
+$ sbx --cloud run --rm claude
+```
+
+The detach gesture is turned off for that session, and you can't combine
+`--rm` with `--detached`. If the session ends without completing, for example
+because the connection drops, the sandbox is kept and the CLI prints the
+command to remove it.
+
 ## Use persistent volumes
 
 Cloud volumes are experimental and preserve data independently of a sandbox.
diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md
index 98578619f2..6ddc9f5459 100644
--- a/content/manuals/ai/sandboxes/usage.md
+++ b/content/manuals/ai/sandboxes/usage.md
@@ -67,6 +67,23 @@ 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.
 
+### Remove a sandbox when the agent exits
+
+Pass `--rm` to `sbx run` for a throwaway session. The sandbox is removed when
+the agent exits, without a confirmation prompt:
+
+```console
+$ sbx run --rm claude
+```
+
+The sandbox is removed however the agent exits, and `sbx run` exits with the
+agent's exit status. If `sbx run` created the sandbox and the agent fails
+to start, the sandbox is also removed. If you reattach to an existing sandbox
+with `--rm`, that sandbox is removed only after its agent session finishes.
+
+`--rm` needs an attached agent session to know when to remove the sandbox, so
+you can't combine it with `--detached` or `--detach-keys`.
+
 ## Choose a workspace
 
 `sbx run` mounts the current directory when you don't pass a workspace path.