From db21c2d397f64667ef7b43797141a8918be7f351 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 15 Jan 2026 03:52:52 +0000
Subject: [PATCH] docs: clarify group sandbox folder allowlist

---
 docs/concepts/groups.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/concepts/groups.md b/docs/concepts/groups.md
index e11408699..51aa5dbc3 100644
--- a/docs/concepts/groups.md
+++ b/docs/concepts/groups.md
@@ -83,9 +83,32 @@ Example (DMs on host, groups sandboxed + messaging-only tools):
 }
 ```
 
+Want “groups can only see folder X” instead of “no host access”? Keep `workspaceAccess: "none"` and mount only allowlisted paths into the sandbox:
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "non-main",
+        scope: "session",
+        workspaceAccess: "none",
+        docker: {
+          binds: [
+            // hostPath:containerPath:mode
+            "~/FriendsShared:/data:ro"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
 Related:
 - Configuration keys and defaults: [Gateway configuration](/gateway/configuration#agentsdefaultssandbox)
 - Debugging why a tool is blocked: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)
+- Bind mounts details: [Sandboxing](/gateway/sandboxing#custom-bind-mounts)
 
 ## Display labels
 - UI labels use `displayName` when available, formatted as `<channel>:<token>`.