From 04ee9e77657843bfb43bfada36d49b3ee9ef6b79 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Tue, 20 Jan 2026 15:00:03 +0000
Subject: [PATCH] docs: clarify sandbox env + recreate guidance

---
 docs/cli/sandbox.md             |  3 +++
 docs/gateway/sandboxing.md      |  7 +++++++
 docs/gateway/troubleshooting.md | 11 +++++++++++
 docs/tools/skills-config.md     | 11 +++++++++++
 4 files changed, 32 insertions(+)

diff --git a/docs/cli/sandbox.md b/docs/cli/sandbox.md
index d98ba7f67..139ebe264 100644
--- a/docs/cli/sandbox.md
+++ b/docs/cli/sandbox.md
@@ -114,6 +114,9 @@ clawdbot sandbox recreate --agent alfred
 
 **Solution:** Use `clawdbot sandbox recreate` to force removal of old containers. They'll be recreated automatically with current settings when next needed.
 
+Tip: prefer `clawdbot sandbox recreate` over manual `docker rm`. It uses the
+Gateway’s container naming and avoids mismatches when scope/session keys change.
+
 ## Configuration
 
 Sandbox settings live in `~/.clawdbot/clawdbot.json` under `agents.defaults.sandbox` (per-agent overrides go in `agents.list[].sandbox`):
diff --git a/docs/gateway/sandboxing.md b/docs/gateway/sandboxing.md
index a3d81dc0d..b9b1bd8fe 100644
--- a/docs/gateway/sandboxing.md
+++ b/docs/gateway/sandboxing.md
@@ -105,6 +105,11 @@ Build it once:
 scripts/sandbox-setup.sh
 ```
 
+Note: the default image does **not** include Node. If a skill needs Node (or
+other runtimes), either bake a custom image or install via
+`sandbox.docker.setupCommand` (requires network egress + writable root +
+root user).
+
 Sandboxed browser image:
 ```bash
 scripts/sandbox-browser-setup.sh
@@ -129,6 +134,8 @@ 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"`).
+- Sandbox exec does **not** inherit host `process.env`. Use
+  `agents.defaults.sandbox.docker.env` (or a custom image) for skill API keys.
 
 ## Tool policy + escape hatches
 Tool allow/deny policies still apply before sandbox rules. If a tool is denied
diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md
index f85ec74c2..3065d5754 100644
--- a/docs/gateway/troubleshooting.md
+++ b/docs/gateway/troubleshooting.md
@@ -87,6 +87,17 @@ WhatsApp + Telegram channels require **Node**; Bun is unsupported. If your
 service was installed with Bun or a version-managed Node path, run `clawdbot doctor`
 to migrate to a system Node install.
 
+### Skill missing API key in sandbox
+
+**Symptom:** Skill works on host but fails in sandbox with missing API key.
+
+**Why:** sandboxed exec runs inside Docker and does **not** inherit host `process.env`.
+
+**Fix:**
+- set `agents.defaults.sandbox.docker.env` (or per-agent `agents.list[].sandbox.docker.env`)
+- or bake the key into your custom sandbox image
+- then run `clawdbot sandbox recreate --agent <id>` (or `--all`)
+
 ### Service Running but Port Not Listening
 
 If the service reports **running** but nothing is listening on the gateway port,
diff --git a/docs/tools/skills-config.md b/docs/tools/skills-config.md
index 64c6cc28b..11d95eead 100644
--- a/docs/tools/skills-config.md
+++ b/docs/tools/skills-config.md
@@ -62,3 +62,14 @@ Per-skill fields:
 - Keys under `entries` map to the skill name by default. If a skill defines
   `metadata.clawdbot.skillKey`, use that key instead.
 - Changes to skills are picked up on the next agent turn when the watcher is enabled.
+
+### Sandboxed skills + env vars
+
+When a session is **sandboxed**, skill processes run inside Docker. The sandbox
+does **not** inherit the host `process.env`.
+
+Use one of:
+- `agents.defaults.sandbox.docker.env` (or per-agent `agents.list[].sandbox.docker.env`)
+- bake the env into your custom sandbox image
+
+Global `env` and `skills.entries.<skill>.env/apiKey` apply to **host** runs only.