feat: auto-recreate sandbox containers on config change

docs/cli/sandbox.md

@@ -89,6 +89,15 @@ clawdbot sandbox recreate --all
 clawdbot sandbox recreate --all
 ```
 
+### After changing setupCommand
+
+```bash
+clawdbot sandbox recreate --all
+# or just one agent:
+clawdbot sandbox recreate --agent family
+```
+
+
 ### For a specific agent only
 
 ```bash

docs/concepts/multi-agent.md

@@ -293,6 +293,9 @@ Starting with v2026.1.6, each agent can have its own sandbox and tool restrictio
 }
 ```
 
+Note: `setupCommand` lives under `sandbox.docker` and runs once on container creation.
+Per-agent `sandbox.docker.*` overrides are ignored when the resolved scope is `"shared"`.
+
 **Benefits:**
 - **Security isolation**: Restrict tools for untrusted agents
 - **Resource control**: Sandbox specific agents while keeping others on host

docs/gateway/configuration.md

@@ -1990,6 +1990,9 @@ cross-session isolation. Use `scope: "session"` for per-session isolation.
 Legacy: `perSession` is still supported (`true` → `scope: "session"`,
 `false` → `scope: "shared"`).
 
+`setupCommand` runs **once** after the container is created (inside the container via `sh -lc`).
+For package installs, ensure network egress, a writable root FS, and a root user.
+
 ```json5
 {
   agents: {

docs/gateway/sandboxing.md

@@ -116,6 +116,20 @@ Override with `agents.defaults.sandbox.docker.network`.
 Docker installs and the containerized gateway live here:
 [Docker](/install/docker)
 
+## setupCommand (one-time container setup)
+`setupCommand` runs **once** after the sandbox container is created (not on every run).
+It executes inside the container via `sh -lc`.
+
+Paths:
+- Global: `agents.defaults.sandbox.docker.setupCommand`
+- Per-agent: `agents.list[].sandbox.docker.setupCommand`
+
+
+Common pitfalls:
+- Default `docker.network` is `"none"` (no egress), so package installs will fail.
+- `readOnlyRoot: true` prevents writes; set `readOnlyRoot: false` or bake a custom image.
+- `user` must be root for package installs (omit `user` or set `user: "0:0"`).
+
 ## Tool policy + escape hatches
 Tool allow/deny policies still apply before sandbox rules. If a tool is denied
 globally or per-agent, sandboxing doesn’t bring it back.

docs/install/docker.md

@@ -254,6 +254,14 @@ precedence, and troubleshooting.
 
 ### Enable sandboxing
 
+If you plan to install packages in `setupCommand`, note:
+- Default `docker.network` is `"none"` (no egress).
+- `readOnlyRoot: true` blocks package installs.
+- `user` must be root for `apt-get` (omit `user` or set `user: "0:0"`).
+Clawdbot auto-recreates containers when `setupCommand` (or docker config) changes
+unless the container was **recently used** (within ~5 minutes). Hot containers
+log a warning with the exact `clawdbot sandbox recreate ...` command.
+
 ```json5
 {
   agents: {

docs/multi-agent-sandbox-tools.md

@@ -18,6 +18,9 @@ This allows you to run multiple agents with different security profiles:
 - Family/work agents with restricted tools
 - Public-facing agents in sandboxes
 
+`setupCommand` belongs under `sandbox.docker` (global or per-agent) and runs once
+when the container is created.
+
 Auth is per-agent: each agent reads from its own `agentDir` auth store at:
 
 ```

docs/tools/skills.md

@@ -111,6 +111,8 @@ Note on sandboxing:
 - `requires.bins` is checked on the **host** at skill load time.
 - If an agent is sandboxed, the binary must also exist **inside the container**.
   Install it via `agents.defaults.sandbox.docker.setupCommand` (or a custom image).
+  `setupCommand` runs once after the container is created.
+  Package installs also require network egress, a writable root FS, and a root user in the sandbox.
   Example: the `summarize` skill (`skills/summarize/SKILL.md`) needs the `summarize` CLI
   in the sandbox container to run there.