Skip to content

Commit 0392cff

Browse files
committed
docs: trim sandbox usage git guidance
Usage still had a Git workflow section after the workflow refactor. Rename it to Git workspace modes and keep only the basic direct versus clone-mode command behavior.
1 parent 2377314 commit 0392cff

1 file changed

Lines changed: 26 additions & 49 deletions

File tree

content/manuals/ai/sandboxes/usage.md

Lines changed: 26 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -128,41 +128,24 @@ to switch between the sandboxes panel and the network panel.
128128
From the network panel you can browse connection logs, allow or block specific
129129
hosts, 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

Comments
 (0)