diff --git a/content/manuals/ai/sandboxes/agents/claude-code.md b/content/manuals/ai/sandboxes/agents/claude-code.md index f52438a91b..931a5d7f84 100644 --- a/content/manuals/ai/sandboxes/agents/claude-code.md +++ b/content/manuals/ai/sandboxes/agents/claude-code.md @@ -109,11 +109,11 @@ use Claude Code's auto mode or pass the flag explicitly: $ sbx run --clone claude . -- --dangerously-skip-permissions agents ``` -Claude Code may use branches or worktrees to keep changes from its background -sessions separate. This depends on the task, Claude Code configuration, and -project instructions. The `--clone` flag doesn't control this behavior. Claude -Code creates any branches and worktrees inside the sandbox, not in your host -checkout. +For simultaneous tasks, each background session needs a separate worktree or +clone. Branches alone don't isolate edits in one working directory. How Claude +Code manages working directories depends on the task, configuration, and +project instructions. The `--clone` flag doesn't control this behavior. Ask +Claude Code to create a separate worktree for each task inside the sandbox. To review a branch created by a session, fetch the `sandbox-` remote from the host: diff --git a/content/manuals/ai/sandboxes/workflows/_index.md b/content/manuals/ai/sandboxes/workflows/_index.md index 7a70ff7774..bcbbf6d45d 100644 --- a/content/manuals/ai/sandboxes/workflows/_index.md +++ b/content/manuals/ai/sandboxes/workflows/_index.md @@ -16,7 +16,9 @@ local sandboxes in automation. For command syntax and lifecycle basics, see Your workspace strategy determines when an agent's changes appear on the host. Direct mode edits the host working tree in place. Clone mode keeps changes in a private clone until you fetch or push them. Host worktrees provide branch -isolation while keeping Git operations on the host. See [Git workflows](git.md) +isolation while keeping Git operations on the host. Mountless sandboxes keep +repositories inside the sandbox, with branches pushed to a Git remote for +review or use on the host. See [Git workflows](git.md) to choose a strategy for single or parallel tasks. ## Develop in the sandbox diff --git a/content/manuals/ai/sandboxes/workflows/git.md b/content/manuals/ai/sandboxes/workflows/git.md index 47289832b1..958f3c65d4 100644 --- a/content/manuals/ai/sandboxes/workflows/git.md +++ b/content/manuals/ai/sandboxes/workflows/git.md @@ -2,7 +2,7 @@ title: Use Git with sandboxes linkTitle: Git workflows weight: 10 -description: Choose a Git workspace mode and manage branches, parallel tasks, and signed commits with Docker Sandboxes. +description: Choose where your Git checkout lives and manage branches, parallel tasks, and signed commits with Docker Sandboxes. keywords: docker sandboxes, sbx, git, clone mode, direct mode, worktrees, branches, commit signing --- @@ -12,23 +12,46 @@ To copy a sandbox filesystem between environments, see [Move a sandbox](../cloud/move.md). Host mounts and clone-mode volumes are not included in that snapshot. -Sandboxes support three approaches for working with Git repositories. The -right choice depends on whether you want branch isolation and whether you -plan to run tasks in parallel: +Choose where your checkout lives based on how you want to review and run the +agent's changes: -| | Direct mode | Clone mode (`--clone`) | Host worktree | -| ------------------------- | ---------------- | ---------------------------- | ----------------------------- | -| Branch management | You, on the host | Agent, inside the clone | You, on the host | -| Changes visible on host | Immediately | After fetch or agent push | Immediately | -| Agent can use Git | Yes | Yes | No | -| Parallelism | No | Multiple agents, one sandbox | One sandbox per parallel task | -| Mode fixed at create time | No | Yes | — | +- Share a host checkout with [direct mode](#direct-mode) to see edits in your + local editor as they happen. A [host worktree](#host-worktree) gives a task + its own branch and directory while keeping edits visible on the host. +- Use [clone mode](#clone-mode) to give the agent a separate checkout based on + your local repository. Fetch or push committed work to bring it back. +- Use a [mountless sandbox](#mountless-sandbox) to clone repositories inside + the sandbox without attaching a host workspace. Push branches to a Git + remote to share the results. + +| Checkout | Changes visible in host checkout | Agent can use Git | +| --- | --- | --- | +| Direct mount | Immediately | Yes | +| Mounted host worktree | Immediately, in the worktree | No | +| Clone mode (`--clone`) | After checking out or merging a fetched branch | Yes | +| Mountless sandbox | After pulling committed work from a Git remote | Yes | + +As you give the agent more responsibility for managing work, consider a +mountless sandbox. The agent can manage branches, create worktrees, and push +results for review without coordinating changes in your host checkout. You +review and bring back committed work through Git, and run previews through +published sandbox ports. + +For simultaneous tasks, have the agent create a separate worktree or clone +for each task inside the sandbox. This works in both mountless sandboxes and +clone mode, and keeps Git available to the agent. Branches alone don't isolate +edits in a shared working directory. Worktrees inside one sandbox share its +tools and services. Use separate sandboxes when tasks also need independent +environments. ## Direct mode -The simplest approach. The sandbox mounts your host working tree directly — -the agent edits files in place and changes appear immediately. You manage -branches yourself. +The sandbox mounts your host working tree directly. The agent edits files in +place, and changes appear immediately. Both you and the agent can use Git, +so agree on who manages branches and commits. Switching branches from either +side changes the files both sides see. + +To manage Git operations from the host: 1. Check out the branch you want to work on: @@ -52,10 +75,8 @@ branches yourself. $ git push -u origin feat/my-feature ``` -Because the sandbox mounts your working tree, switching branches on the host -also changes what the agent sees. This makes direct mode well-suited for -focused, single-branch work where you're collaborating with the agent -turn-by-turn. +Direct mode suits focused, single-branch work where you collaborate with the +agent turn-by-turn. ## Clone mode @@ -68,7 +89,7 @@ access. The sandbox clone is not a Git worktree linked to your host checkout. A single clone-mode sandbox can hold multiple branches and worktrees for parallel tasks. The `--clone` flag creates the clone, but it doesn't separate one task from another. To keep parallel tasks isolated, instruct your agent tool -to create a separate branch or worktree for each task. +to create a separate worktree or clone for each task. > [!NOTE] > `--clone` is a create-time flag and cannot be changed on an existing @@ -136,11 +157,12 @@ It's only reachable while the sandbox is running: ``` 2. Dispatch each independent task to a separate background session. Your agent - tool may use branches or worktrees to keep their changes separate. If it - doesn't, add a project instruction such as: + tool controls how it separates their working directories. To require a + separate worktree for each task, add a project instruction such as: ```markdown - Always start each task on its own git branch before making changes. + For each simultaneous task, create a separate Git worktree with its own branch + and make all changes for that task in that worktree. ``` 3. Fetch all branches when the agents are done: @@ -161,9 +183,9 @@ only the worktree directory (not the parent repository), it can't resolve the `.git` pointer file and has no Git access. The agent can read and write files, but can't commit, branch, or check status. -This is useful when you want branch isolation without the create-time -commitment of clone mode, and you're comfortable committing from the host -yourself after reviewing the changes. +Use this approach when you want edits visible in a separate host directory +and prefer to handle Git operations yourself. To give the agent Git access in +each working directory, use worktrees inside a mountless or clone-mode sandbox. 1. Create the worktree on the host: @@ -187,6 +209,45 @@ yourself after reviewing the changes. $ gh pr create ``` +## Mountless sandbox + +A mountless sandbox has no host workspace attached. Clone repositories inside +it to keep the checkout, dependencies, and development tools in the sandbox. +Files persist across stops and restarts, but removing the sandbox deletes them. + +You can keep one sandbox per project and reuse it across tasks. The agent can +prepare its tools and create worktrees as needed, so starting another task +doesn't require another host checkout or sandbox. + +1. Create a named sandbox without a workspace path, then attach: + + ```console + $ sbx create --name my-project claude + $ sbx run --name my-project + ``` + + Omitting the path from `sbx create` creates a mountless sandbox. Omitting + it from `sbx run claude` mounts your current host directory instead. + See [Choose a workspace](../usage.md#choose-a-workspace). + +2. Ask the agent to clone your repository inside the sandbox and create a + branch before editing. For simultaneous tasks, ask it to create a separate + worktree for each task. + +3. Review and commit the changes inside the sandbox, then push the branch to + your Git remote. You can fetch that branch in a host checkout or review it + in a pull request. Push any work you want to keep before removing the sandbox. + +You can also create a mountless sandbox with an `sbxenv.yaml` environment file. +Omit `workspace` and any `additionalWorkspaces` mounts, then run `sbx env run`. +See [Sandbox environment files](../configuration/environment-files.md#workspace) +for configuration options. + +For running the application and opening a preview from your host browser, see +[Develop and test locally](development.md#accessing-services-in-the-sandbox). +To work with several host repositories in one sandbox instead, see +[Multiple workspaces](../usage.md#multiple-workspaces). + ## Git ignore rules Git inside a local sandbox preserves host-specific ignore decisions for paths