sandboxes: document --clone and consolidate workspace isolation

content/manuals/ai/sandboxes/_index.md

@@ -72,8 +72,8 @@ the [usage guide](usage.md) for common patterns.
   extending or tailoring sandboxes
 - [Architecture](architecture.md) — microVM isolation, workspace mounting,
   networking
-- [Security](security/) — isolation model, credential handling, network
-  policies, workspace trust
+- [Security](security/) — isolation model, credential handling, and
+  network policies
 - [CLI reference](/reference/cli/sbx/) — full list of `sbx` commands and options
 - [Troubleshooting](troubleshooting.md) — common issues and fixes
 - [FAQ](faq.md) — login requirements, telemetry, etc

content/manuals/ai/sandboxes/agents/claude-code.md

@@ -72,6 +72,40 @@ $ sbx run claude -- --dangerously-skip-permissions -c
 See the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference)
 for available options.
 
+## Agents view
+
+Claude Code's [agents view](https://code.claude.com/docs/en/agent-view)
+dispatches tasks to subagents that work in parallel, each in its own
+Git worktree. Pair it with [clone mode](../usage.md#clone-mode) for an
+isolated multi-agent workflow:
+
+```console
+$ sbx run --clone claude -- agents
+```
+
+This invocation replaces the
+[default startup command](#default-startup-command), so it doesn't
+include `--dangerously-skip-permissions` and you can't switch to
+bypass-permissions mode inside the sandbox. Either pass the flag too:
+
+```console
+$ sbx run --clone claude -- --dangerously-skip-permissions agents
+```
+
+or use Claude Code's auto mode.
+
+The subagents' worktrees live inside the sandbox's private clone — none
+of them touches your host repository. Each subagent commits to its own
+branch, and you review the work from the host by fetching the
+`sandbox-<sandbox-name>` remote:
+
+```console
+$ git fetch sandbox-<sandbox-name>
+$ git diff main..sandbox-<sandbox-name>/<branch>
+```
+
+See [Git workflow](../usage.md#git-workflow) for clone-mode details.
+
 ## Base image
 
 The sandbox uses `docker/sandbox-templates:claude-code`. See

content/manuals/ai/sandboxes/get-started.md

@@ -268,5 +268,6 @@ working tree are unaffected.
 - [Customize](customize/) — build reusable templates or declare capabilities
   with kits
 - [Credentials](security/credentials.md) — credential storage and management
-- [Workspace trust](security/workspace.md) — review agent changes safely
+- [Workspace isolation](security/isolation.md#workspace-isolation) — what
+  the agent can affect on your host, and how to review changes
 - [Policies](security/policy.md) — control outbound access

content/manuals/ai/sandboxes/security/_index.md

@@ -18,9 +18,10 @@ anything on your host except what is explicitly shared.
 
 What crosses the boundary into the VM:
 
-- **Workspace directory:** mounted into the VM with read-write access. With
-  the default direct mount, changes the agent makes appear on your host
-  immediately.
+- **Workspace directory:** mounted into the VM. The default direct mount is
+  read-write — the agent edits your working tree in place. With
+  [`--clone`](../usage.md#clone-mode), your repository is mounted read-only
+  and the agent works on a private clone.
 - **Credentials:** the host-side proxy injects authentication headers into
   outbound HTTP requests. The raw credential values never enter the VM.
 - **Network access:** HTTP and HTTPS requests to
@@ -41,7 +42,7 @@ and ICMP are blocked at the network layer.
 
 ## Isolation layers
 
-The sandbox security model has four layers. See
+The sandbox security model has five layers. See
 [Isolation layers](isolation/) for technical details on each.
 
 - **Hypervisor isolation:** separate kernel per sandbox. No shared memory or
@@ -50,6 +51,10 @@ The sandbox security model has four layers. See
   [Deny-by-default policy](defaults/). Non-HTTP protocols blocked entirely.
 - **Docker Engine isolation:** each sandbox has its own Docker Engine with no
   path to the host daemon.
+- **Workspace isolation:** with `--clone`, the agent works on a private
+  in-VM clone and your repository is mounted read-only. In direct mode
+  (default), the agent edits your working tree directly — no boundary
+  applies.
 - **Credential isolation:** API keys are injected into HTTP headers by the
   host-side proxy. Credential values never enter the VM.
 
@@ -66,13 +71,15 @@ permitted and what is blocked.
 The sandbox isolates the agent from your host system, but the agent's actions
 can still affect you through the shared workspace and allowed network channels.
 
-**Workspace changes are live on your host.** The agent edits the same files you
-see on your host. This includes files that execute implicitly during normal
-development: Git hooks, CI configuration, IDE task configs, `Makefile`,
-`package.json` scripts, and similar build files. Review changes before running
-any modified code. Note that Git hooks live inside `.git/` and do not appear in
-`git diff` output. Check them separately.
-See [Workspace trust](workspace/).
+**Workspace changes are live on your host in direct mode.** With the default
+direct mount, the agent edits the same files you see on your host. This
+includes files that execute implicitly during normal development: Git hooks,
+CI configuration, IDE task configs, `Makefile`, `package.json` scripts, and
+similar build files. Review changes before running any modified code. Note
+that Git hooks live inside `.git/` and do not appear in `git diff` output —
+check them separately. See
+[Workspace isolation](isolation/#workspace-isolation) for the full list and
+for the alternative clone-mode boundary.
 
 **Default allowed domains include broad wildcards.** Some defaults like
 `*.googleapis.com` cover many services beyond AI APIs. Run `sbx policy ls` to
@@ -93,12 +100,11 @@ See [Organization governance](governance/) for details.
 
 ## Learn more
 
-- [Isolation layers](isolation/): how hypervisor, network, Docker, and
-  credential isolation work
+- [Isolation layers](isolation/): how hypervisor, network, Docker,
+  workspace, and credential isolation work
 - [Default security posture](defaults/): what a fresh sandbox permits and
   blocks
 - [Credentials](credentials/): how to provide and manage API keys
 - [Policies](policy/): how to customize network access rules
 - [Organization governance](governance/): centrally manage policies across
   an organization
-- [Workspace trust](workspace/): what to review after an agent session

content/manuals/ai/sandboxes/security/defaults.md

@@ -28,7 +28,8 @@ working tree directly, and changes appear on your host immediately.
 
 The agent can read, write, and delete any file within the workspace directory,
 including hidden files, configuration files, build scripts, and Git hooks.
-See [Workspace trust](workspace.md) for what to review after an agent session.
+See [Workspace isolation](isolation.md#workspace-isolation) for what to
+review after an agent session.
 
 ## Credential defaults
 

content/manuals/ai/sandboxes/security/isolation.md

@@ -1,13 +1,14 @@
 ---
 title: Isolation layers
 weight: 10
-description: How Docker Sandboxes isolate AI agents using hypervisor, network, Docker Engine, and credential boundaries.
-keywords: docker sandboxes, isolation, hypervisor, network, credentials
+description: How Docker Sandboxes isolate AI agents using hypervisor, network, Docker Engine, workspace, and credential boundaries.
+keywords: docker sandboxes, isolation, hypervisor, network, credentials, workspace, git
 ---
 
 AI coding agents need to execute code, install packages, and run tools on
-your behalf. Docker Sandboxes run each agent in its own microVM with four
-isolation layers: hypervisor, network, Docker Engine, and credential proxy.
+your behalf. Docker Sandboxes run each agent in its own microVM. Five
+isolation layers protect your host: hypervisor, network, Docker Engine,
+workspace, and credential proxy.
 
 ## Hypervisor isolation
 
@@ -71,6 +72,106 @@ Host system
            └── [VM] Containers created by agent
 ```
 
+## Workspace isolation
+
+When you create a sandbox, you choose one of two ways to share your
+workspace with it:
+
+- **Direct mount** (the default): the agent has read-write access to
+  your working tree. There is no boundary between the agent's edits and
+  your host filesystem.
+- **Clone mode** (`--clone`): your repository is mounted read-only into
+  the VM and the agent works on a private clone inside the VM. The
+  agent's edits never reach your host until you fetch them.
+
+See [Git workflow](../usage.md#git-workflow) for the workflow side of
+each.
+
+### Direct mount (default)
+
+By default, your workspace is shared into the VM as a read-write mount.
+The agent and the host see the same files, and changes the agent makes
+appear on your host as soon as they're written.
+
+There is no isolation between the agent and your workspace in this mode.
+The agent can create, modify, or delete any file in the workspace,
+including:
+
+- Source code and configuration files
+- Build files (`Makefile`, `package.json`, `Cargo.toml`)
+- Git hooks (`.git/hooks/`)
+- CI configuration (`.github/workflows/`, `.gitlab-ci.yml`)
+- IDE configuration (`.vscode/tasks.json`, `.idea/` run configurations)
+- Hidden files, shell scripts, and executables
+
+Some of these files execute code when you trigger normal development
+actions — committing, pushing, building, or opening the project in an IDE.
+Review them after any agent session before performing those actions:
+
+- **Git hooks** (`.git/hooks/`) run on commit, push, and other Git actions.
+  These are inside `.git/` and **do not appear in `git diff` output** —
+  check them separately with `ls -la .git/hooks/`.
+- **CI configuration** (`.github/workflows/`, `.gitlab-ci.yml`) runs on
+  push.
+- **Build files** (`Makefile`, `package.json` scripts, `Cargo.toml`) run
+  during build or install steps.
+- **IDE configuration** (`.vscode/tasks.json`, `.idea/`) can run tasks
+  when you open the project.
+
+Treat sandbox-modified workspace files the same way you would treat a pull
+request from an untrusted contributor: review before you trust them on
+your host.
+
+### Clone mode
+
+When you start a sandbox with [`--clone`](../usage.md#clone-mode), the agent
+never works directly against your host repository. Even with full root
+inside the VM, it cannot modify your `.git` directory, your working tree,
+or any tracked file on your host.
+
+```plaintext
+Host repository                          Sandbox VM
+  .git/  (untouched)                       private clone  (RW, in VM)
+  working tree  (untouched)                  ↑ agent edits here
+                                             │
+  /run/sandbox/source (RO bind mount) ←──────┘
+  (read-only view of your repo)
+
+  remote sandbox-<name>  ──── git fetch ───► git-daemon (inside VM)
+```
+
+How the boundary is enforced:
+
+- Your repository's Git root is mounted at `/run/sandbox/source` as
+  read-only. Nothing the agent does inside the VM can write back through
+  that mount.
+- The agent works on a private clone that lives inside the sandbox. The
+  clone has its own index, its own refs, and its own working tree. Writes
+  to the clone never reach your host.
+- The sandbox publishes the clone over a Git daemon bound to localhost on
+  the host. The CLI wires it up as a `sandbox-<sandbox-name>` Git remote on
+  your host repository. Fetching from that remote uses the same trust
+  model as fetching from any third-party remote — nothing is integrated
+  until you explicitly merge or check out the fetched refs.
+
+The practical guarantees:
+
+- The agent cannot modify any tracked file or any byte under `.git/` on
+  your host. A compromised or buggy agent cannot drop a
+  `.git/hooks/pre-commit`, alter `.github/workflows/`, or sneak changes
+  into your working tree.
+- Concurrent `git` commands on the host and inside the sandbox cannot
+  race on a shared `.git/index` or shared refs — there is no shared
+  writable state.
+- Credentials, signing keys, and any settings in your repository's
+  `.git/config` stay on the host. The agent's clone has its own
+  independent configuration.
+
+Use clone mode whenever you want a strong boundary between the agent's
+Git activity and your host repository — for example when running an
+unfamiliar agent, running multiple agents on the same repository at once,
+or keeping your working tree clean while the agent works.
+
 ## Credential isolation
 
 Most agents need API keys for their model provider. Rather than passing keys