From e05a29395e4c21959133d93fe4319ad04cdc9cc4 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Tue, 6 Jan 2026 23:22:49 +0100
Subject: [PATCH] docs: clarify perSession isolation

---
 CHANGELOG.md          | 1 +
 docs/configuration.md | 5 ++++-
 docs/docker.md        | 3 +++
 docs/security.md      | 3 +++
 4 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f695aa2f8..2c0a8ae13 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -70,6 +70,7 @@
 - Model: avoid duplicate `missing (missing)` auth labels in `/model` list output.
 - Auth: when `openai` has no API key but Codex OAuth exists, suggest `openai-codex/gpt-5.2` vs `OPENAI_API_KEY`.
 - Docs: clarify auth storage, migration, and OpenAI Codex OAuth onboarding.
+- Docs: clarify per-session sandbox isolation and `perSession` sharing risks.
 - Sandbox: copy inbound media into sandbox workspaces so agent tools can read attachments.
 - Sandbox: enable session tools in sandboxed sessions with spawned-only visibility by default (opt-in `agent.sandbox.sessionToolsVisibility = "all"`).
 - Control UI: show a reading indicator bubble while the assistant is responding.
diff --git a/docs/configuration.md b/docs/configuration.md
index 869945fa0..8fc8a76cd 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -859,12 +859,15 @@ Defaults (if enabled):
 - optional sandboxed browser (Chromium + CDP, noVNC observer)
 - hardening knobs: `network`, `user`, `pidsLimit`, `memory`, `cpus`, `ulimits`, `seccompProfile`, `apparmorProfile`
 
+Warning: `perSession: false` means a shared container and shared workspace. No
+cross-session isolation.
+
 ```json5
 {
   agent: {
     sandbox: {
       mode: "non-main", // off | non-main | all
-      perSession: true,
+      perSession: true, // recommended for isolation (false = shared container/workspace)
       workspaceRoot: "~/.clawdbot/sandboxes",
       docker: {
         image: "clawdbot-sandbox:bookworm-slim",
diff --git a/docs/docker.md b/docs/docker.md
index 5950c3fb4..118ab96c2 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -81,6 +81,9 @@ container. The gateway stays on your host, but the tool execution is isolated:
 - allow/deny tool policy (deny wins)
 - inbound media is copied into the sandbox workspace (`media/inbound/*`) so tools can read it
 
+Warning: setting `perSession: false` disables per-session isolation. All sessions
+share one container and one workspace, so there is no cross-session isolation.
+
 ### Default behavior
 
 - Image: `clawdbot-sandbox:bookworm-slim`
diff --git a/docs/security.md b/docs/security.md
index a30d211f6..d0883237f 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -141,6 +141,9 @@ Two complementary approaches:
 - **Run the full Gateway in Docker** (container boundary): https://docs.clawd.bot/docker
 - **Per-session tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): https://docs.clawd.bot/configuration
 
+Note: to prevent cross-agent access, keep `perSession: true` so each session gets
+its own container + workspace. `perSession: false` shares a single container.
+
 Important: `agent.elevated` is an explicit escape hatch that runs bash on the host. Keep `agent.elevated.allowFrom` tight and don’t enable it for strangers.
 
 ## What to Tell Your AI