Docker sbx has expanded the options for where a project's files live when an agent runs inside a sandbox. Practitioners can now mount the host checkout, use separate Git worktrees, or let sbx create a clone inside a mount‑less sandbox. Each pattern changes how you interact with the agent, how dependencies are resolved, and what operational safeguards are needed.
Mounting the Host Checkout
Running sbx run from a project directory binds that directory into the sandbox at the same absolute path. The agent edits the same files you see in your editor, and Git commands are available on both sides. This arrangement enables tight, real‑time collaboration: you can watch changes, hot‑reload a development server, and decide whether the agent or you commit. The trade‑off is that branch switches on the host immediately affect the agent’s view, and any native binaries installed on the host (e.g., esbuild) must be compatible with the sandbox’s Linux environment. If they are not, you must reinstall dependencies in the appropriate environment.
Separate Worktrees per Task
Git worktrees let you create a dedicated directory and branch for each agent task. By mounting a worktree into its own sandbox, the agent’s edits stay isolated from your main checkout while you retain the ability to inspect changes locally. The limitation is that a linked worktree’s .git file points outside the mount, preventing the agent from running full Git operations; status, branching, and committing must be performed on the host. Nevertheless, this pattern reduces coordination overhead when multiple tasks run concurrently, because each worktree has its own environment and can be cleaned up after the task finishes.
Clone Mode and Mount‑less Sandboxes
In clone mode, sbx mounts the host source read‑only and creates an independent Git clone inside the sandbox. The agent works on its own branch, installs dependencies, and pushes results to a remote that sbx adds on the host. Your local editor only sees changes after you merge or pull the remote branch. A fully mount‑less sandbox follows the same principle but clones the repository directly inside the container, eliminating any host‑side connection. This model mirrors remote development machines: the sandbox holds both code and toolchain, and you interact via sbx exec or an SSH‑based editor connection. To retrieve work, you push a branch to the remote repository; deleting the sandbox discards any files that were never pushed.
Operational and Security Considerations
Each placement strategy introduces distinct operational concerns. Host‑mounted checkouts share dependency binaries, so mismatched OS architectures can cause runtime failures. Separate worktrees mitigate this but still expose the host’s .git metadata, requiring careful branch management. Clone‑mode sandboxes isolate dependencies completely, reducing the risk of host‑sandbox contamination, but they add a hand‑off step to synchronize code back to the host. When multiple repositories are needed for a task, sbx can mount additional read‑only directories, but any writable checkout still demands coordination of branches and commits. Port publishing (e.g., sbx ports my-sandbox --publish 8080:8080) is required for previewing services running inside the sandbox, adding a small amount of ceremony compared to local development.
Related CloudNinjas coverage: hands-on guides.
What This Means For Practitioners
Pick the placement model that matches your workflow:
- Live co‑editing: mount the host checkout if you need immediate visibility of agent changes.
- Task isolation: use per‑task worktrees when you want separate branches without full sandbox cloning.
- Dependency safety and reproducibility: adopt clone‑mode or mount‑less sandboxes for clean environments and easier CI integration.
Evaluate the need for read‑only reference repositories, the overhead of pushing branches back to a remote, and the compatibility of native binaries across host and sandbox. Align the chosen pattern with your team's collaboration style, CI pipelines, and security posture to avoid unexpected breakages and to keep agent‑driven work predictable.