@@ -128,41 +128,24 @@ to switch between the sandboxes panel and the network panel.
128128From the network panel you can browse connection logs, allow or block specific
129129hosts, and add custom network rules. Press ` ? ` to see all keyboard shortcuts.
130130
131- ## Git workflow
132-
133- When your workspace is a Git repository, you can share it with a sandbox in one
134- of two ways:
135-
136- - Direct mode (default): the agent has read-write access to your
137- working tree. Changes the agent makes appear on your host immediately.
138- - [ Clone mode] ( #clone-mode ) (` --clone ` ): the agent works on a private
139- Git clone inside the sandbox, with your host repository mounted
140- read-only. The sandbox exposes its clone as a Git remote on your host,
141- so you fetch the agent's commits the same way you'd fetch from any
142- other remote.
143-
144- For a comparison of approaches and workflow recipes, see
145- [ Workflow patterns] ( workflows.md#git-workflows ) . For the security model
146- behind each mode, see
147- [ Workspace isolation] ( security/isolation.md#workspace-isolation ) .
131+ ## Git workspace modes
148132
149- ### Direct mode (default)
133+ When your primary workspace is a Git repository, choose how the sandbox receives
134+ it when you create the sandbox:
150135
151- The agent edits your working tree directly. Stage, commit, and push from the
152- host as you normally would. If you run multiple agents on the same repository at
153- the same time, use [ clone mode] ( #clone-mode ) to give each agent an isolated
154- workspace .
136+ - Direct mode is the default. The agent has read-write access to your working
137+ tree, and changes appear on your host immediately.
138+ - [ Clone mode] ( #clone-mode ) uses ` --clone ` . The agent works in a private Git
139+ clone inside the sandbox, and your host repository is mounted read-only .
155140
156- ### Clone mode
141+ For guidance on branch strategy, fetching work from a sandbox, and parallel
142+ agent workflows, see [ Git workflows] ( workflows.md#git-workflows ) . For the
143+ security model behind each mode, see
144+ [ Workspace isolation] ( security/isolation.md#workspace-isolation ) .
157145
158- In clone mode, the sandbox becomes a Git remote on your host. Your entire
159- working directory, including untracked files and files excluded by ` .gitignore ` ,
160- is mounted read-only inside the sandbox. The agent commits inside the sandbox.
161- You pull its work back out by fetching from that remote:
146+ ### Clone mode
162147
163- ``` console
164- $ git fetch sandbox-< name>
165- ```
148+ To create a clone-mode sandbox, pass ` --clone ` when you run or create it:
166149
167150``` console
168151$ sbx run --clone claude
@@ -175,25 +158,19 @@ $ sbx create --clone --name my-sandbox claude .
175158$ sbx run --name my-sandbox
176159```
177160
178- The clone follows whichever ref your host repository has checked out at
179- create time. No branch is created automatically.
180-
181- Clone mode is fixed at create time. To switch an existing sandbox to clone mode,
182- remove it and recreate it with ` sbx create --clone ` .
183-
184- > [ !WARNING]
185- > Removing a clone-mode sandbox drops the in-sandbox clone along with it.
186- > Any commits you haven't fetched (` git fetch sandbox-<name> ` ) or pushed
187- > to an upstream remote are lost. ` sbx rm ` prints a warning before
188- > deleting a clone-mode sandbox — review it before confirming.
189-
190- Clone mode requires a Git repository as the primary workspace, and is
191- rejected at create time in two cases:
192-
193- - ` --clone ` on a non-Git workspace. Omit ` --clone ` for non-Git workspaces.
194- - ` --clone ` from inside a Git worktree (other than the main one). The
195- read-only bind mount can't resolve the worktree's ` .git ` pointer file.
196- Run ` sbx create --clone ` from the main repository checkout instead.
161+ Clone mode has a few create-time constraints:
162+
163+ - Clone mode is fixed at create time. To switch an existing sandbox to clone
164+ mode, remove it and recreate it with ` sbx create --clone ` .
165+ - The clone follows whichever ref your host repository has checked out at create
166+ time. No branch is created automatically.
167+ - The primary workspace must be a Git repository. Omit ` --clone ` for non-Git
168+ workspaces.
169+ - Clone mode is rejected from inside a Git worktree other than the main one. The
170+ read-only bind mount can't resolve the worktree's ` .git ` pointer file. Run
171+ ` sbx create --clone ` from the main repository checkout instead.
172+ - Removing a clone-mode sandbox drops the in-sandbox clone. Fetch or push any
173+ commits you want to keep before you remove it.
197174
198175## Multiple workspaces
199176
0 commit comments