From 57d3d6bd784d3b1f9c8e225e5373f9148cee2d80 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 9 Jan 2026 01:54:28 +0100
Subject: [PATCH] docs: clarify workspace vs sandbox

---
 docs/concepts/agent-workspace.md |  5 +++++
 docs/concepts/multi-agent.md     |  5 +++++
 docs/start/faq.md                | 20 ++++++++++++++++++++
 3 files changed, 30 insertions(+)

diff --git a/docs/concepts/agent-workspace.md b/docs/concepts/agent-workspace.md
index 83af0a43f..2b0ea5924 100644
--- a/docs/concepts/agent-workspace.md
+++ b/docs/concepts/agent-workspace.md
@@ -12,6 +12,11 @@ file tools and for workspace context. Keep it private and treat it as memory.
 This is separate from `~/.clawdbot/`, which stores config, credentials, and
 sessions.
 
+**Important:** the workspace is the **default cwd**, not a hard sandbox. Tools
+resolve relative paths against the workspace, but absolute paths can still reach
+elsewhere on the host unless sandboxing is enabled. If you need isolation, use
+[`agent.sandbox`](/gateway/sandboxing) (and/or per‑agent sandbox config).
+
 ## Default location
 
 - Default: `~/clawd`
diff --git a/docs/concepts/multi-agent.md b/docs/concepts/multi-agent.md
index 8a3323418..67429b9e7 100644
--- a/docs/concepts/multi-agent.md
+++ b/docs/concepts/multi-agent.md
@@ -22,6 +22,11 @@ available from `~/.clawdbot/skills`. See [Skills: per-agent vs shared](/tools/sk
 
 The Gateway can host **one agent** (default) or **many agents** side-by-side.
 
+**Workspace note:** each agent’s workspace is the **default cwd**, not a hard
+sandbox. Relative paths resolve inside the workspace, but absolute paths can
+reach other host locations unless sandboxing is enabled. See
+[Sandboxing](/gateway/sandboxing).
+
 ## Paths (quick map)
 
 - Config: `~/.clawdbot/clawdbot.json` (or `CLAWDBOT_CONFIG_PATH`)
diff --git a/docs/start/faq.md b/docs/start/faq.md
index d286b6196..507e1a30c 100644
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -114,6 +114,26 @@ Legacy single‑agent path: `~/.clawdbot/agent/*` (migrated by `clawdbot doctor`
 
 Your **workspace** (AGENTS.md, memory files, skills, etc.) is separate and configured via `agent.workspace` (default: `~/clawd`).
 
+### Can agents work outside the workspace?
+
+Yes. The workspace is the **default cwd** and memory anchor, not a hard sandbox.
+Relative paths resolve inside the workspace, but absolute paths can access other
+host locations unless sandboxing is enabled. If you need isolation, use
+[`agent.sandbox`](/gateway/sandboxing) or per‑agent sandbox settings. If you
+want a repo to be the default working directory, point that agent’s
+`workspace` to the repo root. The Clawdbot repo is just source code; keep the
+workspace separate unless you intentionally want the agent to work inside it.
+
+Example (repo as default cwd):
+
+```json5
+{
+  agent: {
+    workspace: "~/Projects/my-repo"
+  }
+}
+```
+
 ### I’m in remote mode — where is the session store?
 
 Session state is owned by the **gateway host**. If you’re in remote mode, the session store you care about is on the remote machine, not your local laptop. See [Session management](/concepts/session).