Skip to content

sbx: clarify clone behavior #25423

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
craig-osterhout wants to merge 4 commits into
base: main
Choose a base branch
from
+11 −5
Open

sbx: clarify clone behavior #25423

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6b8f42e
sbx: clarify clone behavior
craig-osterhout Jun 23, 2026
cf49d47
separate bullet
craig-osterhout Jun 23, 2026
ee05b07
move limitation out of benefit
craig-osterhout Jun 23, 2026
e96b460
update file example
craig-osterhout Jun 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions content/manuals/ai/sandboxes/security/isolation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,8 +165,10 @@ flowchart LR
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.
read-only. The mount covers your entire working directory, including
untracked files and files excluded by `.gitignore`. Nothing the agent
does inside the VM can write back through that mount, but all files
under the Git root are readable inside the sandbox.
- 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.
Expand All @@ -187,7 +189,11 @@ The practical guarantees:
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.
independent configuration. Credential files in your working directory that aren't tracked by Git,
Comment thread
craig-osterhout marked this conversation as resolved.
Outdated
including those excluded by `.gitignore`, such as `.envrc.private`, are
readable inside the sandbox.
Store secrets outside your working directory or use
Comment thread
craig-osterhout marked this conversation as resolved.
Outdated
[credential isolation](credentials.md) instead.

Use clone mode whenever you want a strong boundary between the agent's
Git activity and your host repository — for example when running an
Expand Down
7 changes: 4 additions & 3 deletions content/manuals/ai/sandboxes/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,9 +99,10 @@ same time, they may step on each other's changes — use

### Clone mode

In clone mode, the sandbox becomes a Git remote on your host. The agent
commits inside the sandbox; you pull its work back out by fetching from
that remote.
In clone mode, the sandbox becomes a Git remote on your host. Your entire
working directory, including untracked files and files excluded by `.gitignore`, is mounted
read-only inside the sandbox. The agent commits inside the sandbox; you pull its work back
out by fetching from that remote.

> [!NOTE]
> Clone mode was introduced in `sbx` v0.31.0 and replaces the `--branch`
Expand Down