From 75927d736a9e431235b21c18ea5272a06c99a94e Mon Sep 17 00:00:00 2001
From: sheeek <gitlab@ott.team>
Date: Fri, 9 Jan 2026 09:40:46 +0100
Subject: [PATCH] docs: add sandbox CLI documentation

---
 docs/cli/sandbox.md | 118 ++++++++++++++++++++++++++++++++++++++++++++
 docs/docs.json      |   3 +-
 2 files changed, 120 insertions(+), 1 deletion(-)
 create mode 100644 docs/cli/sandbox.md

diff --git a/docs/cli/sandbox.md b/docs/cli/sandbox.md
new file mode 100644
index 000000000..a6a08a788
--- /dev/null
+++ b/docs/cli/sandbox.md
@@ -0,0 +1,118 @@
+# Sandbox CLI
+
+Manage Docker-based sandbox containers for isolated agent execution.
+
+## Overview
+
+ClawdBot can run agents in isolated Docker containers for security. The `sandbox` commands help you manage these containers, especially after updates or configuration changes.
+
+## Commands
+
+### `clawd sandbox list`
+
+List all sandbox containers with their status and configuration.
+
+```bash
+clawd sandbox list
+clawd sandbox list --browser  # List only browser containers
+clawd sandbox list --json     # JSON output
+```
+
+**Output includes:**
+- Container name and status (running/stopped)
+- Docker image and whether it matches config
+- Age (time since creation)
+- Idle time (time since last use)
+- Associated session/agent
+
+### `clawd sandbox recreate`
+
+Remove sandbox containers to force recreation with updated images/config.
+
+```bash
+clawd sandbox recreate --all                # Recreate all containers
+clawd sandbox recreate --session main       # Specific session
+clawd sandbox recreate --agent mybot        # Specific agent
+clawd sandbox recreate --browser            # Only browser containers
+clawd sandbox recreate --all --force        # Skip confirmation
+```
+
+**Options:**
+- `--all`: Recreate all sandbox containers
+- `--session <key>`: Recreate container for specific session
+- `--agent <id>`: Recreate containers for specific agent
+- `--browser`: Only recreate browser containers
+- `--force`: Skip confirmation prompt
+
+**Important:** Containers are automatically recreated when the agent is next used.
+
+## Use Cases
+
+### After updating Docker images
+
+```bash
+# Pull new image
+docker pull clawdbot-sandbox:latest
+docker tag clawdbot-sandbox:latest clawdbot-sandbox:bookworm-slim
+
+# Update config to use new image
+# Edit clawdbot.config.json: agent.sandbox.docker.image
+
+# Recreate containers
+clawd sandbox recreate --all
+```
+
+### After changing sandbox configuration
+
+```bash
+# Edit clawdbot.config.json: agent.sandbox.*
+
+# Recreate to apply new config
+clawd sandbox recreate --all
+```
+
+### For a specific agent only
+
+```bash
+# Update only one agent's containers
+clawd sandbox recreate --agent alfred
+```
+
+## Why is this needed?
+
+**Problem:** When you update sandbox Docker images or configuration:
+- Existing containers continue running with old settings
+- Containers are only pruned after 24h of inactivity
+- Regularly-used agents keep old containers running indefinitely
+
+**Solution:** Use `clawd sandbox recreate` to force removal of old containers. They'll be recreated automatically with current settings when next needed.
+
+## Configuration
+
+Sandbox settings are in `clawdbot.config.json`:
+
+```jsonc
+{
+  "agent": {
+    "sandbox": {
+      "mode": "all",                    // off, non-main, all
+      "scope": "agent",                 // session, agent, shared
+      "docker": {
+        "image": "clawdbot-sandbox:bookworm-slim",
+        "containerPrefix": "clawdbot-sbx-"
+        // ... more Docker options
+      },
+      "prune": {
+        "idleHours": 24,               // Auto-prune after 24h idle
+        "maxAgeDays": 7                // Auto-prune after 7 days
+      }
+    }
+  }
+}
+```
+
+## See Also
+
+- [Sandbox Documentation](../gateway/sandboxing.md)
+- [Agent Configuration](../concepts/agent-workspace.md)
+- [Doctor Command](./doctor.md) - Check sandbox setup
diff --git a/docs/docs.json b/docs/docs.json
index e7737bf55..ac0f48b00 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -553,7 +553,8 @@
         "group": "CLI",
         "pages": [
           "cli/index",
-          "cli/gateway"
+          "cli/gateway",
+          "cli/sandbox"
         ]
       },
       {