From 2377314578ddc2064df154db0487dcf67d6cb490 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 14 Jul 2026 12:46:27 +0000 Subject: [PATCH 1/2] docs: clarify sandbox usage workflows The usage and workflow pages overlapped across Git, CI, ports, and team setup guidance. Refactor Usage into a command primer, move scenario guidance to Workflow patterns, and update cross-references. --- .../claude-code-sandbox-model-runner.md | 2 +- content/manuals/ai/sandboxes/_index.md | 2 +- .../ai/sandboxes/agents/claude-code.md | 6 +- content/manuals/ai/sandboxes/get-started.md | 11 +- .../ai/sandboxes/security/isolation.md | 2 +- .../manuals/ai/sandboxes/troubleshooting.md | 2 +- content/manuals/ai/sandboxes/usage.md | 289 ++++++------------ content/manuals/ai/sandboxes/workflows.md | 161 +++++++++- 8 files changed, 256 insertions(+), 219 deletions(-) diff --git a/content/guides/claude-code-sandbox-model-runner.md b/content/guides/claude-code-sandbox-model-runner.md index 823a58593ee2..8b6e58d7e643 100644 --- a/content/guides/claude-code-sandbox-model-runner.md +++ b/content/guides/claude-code-sandbox-model-runner.md @@ -88,7 +88,7 @@ $ sbx policy allow network localhost:12434 ``` For background on host access from sandboxes, see -[Accessing host services from a sandbox](../manuals/ai/sandboxes/usage.md#accessing-host-services-from-a-sandbox). +[Accessing host services from a sandbox](../manuals/ai/sandboxes/workflows.md#accessing-host-services-from-a-sandbox). ## Step 3: Create a Claude Code sandbox diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index 229b216cb6cb..1a05b57821e4 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/content/manuals/ai/sandboxes/_index.md @@ -68,7 +68,7 @@ $ sbx run claude ``` See the [get started guide](get-started.md) for a full walkthrough, or jump to -the [usage guide](usage.md) for common patterns. +the [usage guide](usage.md) for basic commands. ## Learn more diff --git a/content/manuals/ai/sandboxes/agents/claude-code.md b/content/manuals/ai/sandboxes/agents/claude-code.md index 13b4d0976411..c61ab2ae686a 100644 --- a/content/manuals/ai/sandboxes/agents/claude-code.md +++ b/content/manuals/ai/sandboxes/agents/claude-code.md @@ -38,7 +38,7 @@ Claude Code requires either an Anthropic API key or a Claude subscription. $ sbx secret set -g anthropic ``` -**Claude subscription**: If no API key is set, use the `/login` command inside +**Claude subscription**: If no API key is set, use the `/login` command inside Claude Code to authenticate via OAuth. ## Configuration @@ -75,7 +75,7 @@ for available options. Claude Code's [agents view](https://code.claude.com/docs/en/agent-view) dispatches tasks to subagents that work in parallel, each in its own -Git worktree. Pair it with [clone mode](../usage.md#clone-mode) for an +Git worktree. Pair it with [clone mode](../workflows.md#clone-mode) for an isolated multi-agent workflow: ```console @@ -102,7 +102,7 @@ $ git fetch sandbox- $ git diff main..sandbox-/ ``` -See [Git workflow](../usage.md#git-workflow) for clone-mode details. +See [Git workflows](../workflows.md#git-workflows) for clone-mode details. ## Base image diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 4df5fae07587..7289d445f6e2 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -173,7 +173,7 @@ my-sandbox claude running ~/my-project ``` Each row shows a sandbox's name, the agent running in it, its status, any -[published ports](usage.md#accessing-services-in-the-sandbox), and its +[published ports](usage.md#publish-ports), and its workspace — the host directory shared into the sandbox. That workspace is the one part of your machine the agent can see. @@ -251,14 +251,13 @@ rules from one place. Then explore: -- [Clone mode](usage.md#clone-mode) — give each agent an isolated Git clone - instead of your working tree, so you can run several agents on one repository - in parallel and review each one's commits separately. +- [Usage guide](usage.md) — basic commands, reconnecting, workspaces, and port + publishing. +- [Workflow patterns](workflows.md) — Git strategies, local services, CI, and + authenticated tools. - [Customize with kits](customize/) — package an agent, its tools, and its network rules into a reusable definition you launch with a single flag. - [Agents](agents/) — the full list of supported agents and how to configure each one. - [Governance](governance/) — centrally manage network and filesystem policies across a team. -- [Usage guide](usage.md) — reconnecting, multiple workspaces, port forwarding, - and more. diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index 6d397b4d27a8..5d72cea66660 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -97,7 +97,7 @@ workspace with it: the VM and the agent works on a private clone inside the VM. The agent's edits never reach your host until you fetch them. -See [Git workflow](../usage.md#git-workflow) for the workflow side of +See [Git workflows](../workflows.md#git-workflows) for the workflow side of each. ### Direct mount (default) diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 9b70ef44021d..2b7c24e90cfc 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -103,7 +103,7 @@ $ git clone https://github.com/owner/repo.git If a request to `127.0.0.1` or a local network IP returns "connection refused" from inside a sandbox, the address is not reachable from within the sandbox VM. -See [Accessing host services from a sandbox](usage.md#accessing-host-services-from-a-sandbox). +See [Accessing host services from a sandbox](workflows.md#accessing-host-services-from-a-sandbox). ## Docker authentication failure diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 3482d1a80914..da3b45410abf 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -1,11 +1,25 @@ --- title: Usage weight: 20 -description: Common patterns for working with sandboxes. -keywords: docker sandboxes, sbx, usage, run, policy, secrets, branches, git, workspaces, ssh +description: Basic sbx commands for creating, managing, and connecting to Docker Sandboxes. +keywords: docker sandboxes, sbx, usage, run, create, stop, remove, ports, workspaces --- -## Working with sandboxes +Use this page as a command-oriented guide to day-to-day `sbx` operations. For +scenario-based recommendations, see [Workflow patterns](workflows.md). + +## Sign in + +Sign in from a terminal: + +```console +$ sbx login +``` + +For scripts or CI runners where a browser isn't available, see +[CI and headless use](workflows.md#ci-and-headless-use). + +## Start, stop, and remove The basic workflow is [`run`](/reference/cli/sbx/run/) to start, [`ls`](/reference/cli/sbx/ls/) to check status, @@ -26,34 +40,69 @@ in-flight SFTP transfer — `sbx rm` refuses unless you pass `--force`: $ sbx rm --force my-sandbox ``` -To get a shell inside a running sandbox — useful for inspecting the environment, -checking Docker containers, or manually installing something: +If you need a clean slate, remove the sandbox and run it again: ```console -$ sbx exec -it bash +$ sbx stop my-sandbox +$ sbx rm my-sandbox +$ sbx run claude ``` -If you need a clean slate, remove the sandbox and re-run: +## Reconnect and name sandboxes + +Sandboxes persist after the agent exits. Running the same workspace path again +reconnects to the existing sandbox rather than creating another sandbox: ```console -$ sbx stop my-sandbox -$ sbx rm my-sandbox -$ sbx run claude +$ sbx run claude ~/my-project # creates sandbox +$ sbx run claude ~/my-project # reconnects to same sandbox ``` -## Non-interactive login +Use `--name` to give a sandbox an explicit identity: + +```console +$ sbx run claude --name my-project +``` -For CI environments and scripts where a browser is not available, use a -Docker Personal Access Token (PAT) with `--username` and `--password-stdin`: +Once a named sandbox exists, use `--name` to re-attach to it from any working +directory, with or without the agent positional: ```console -$ echo "$DOCKER_PAT" | sbx login --username --password-stdin +$ sbx run --name my-project # re-attaches from anywhere +$ sbx run claude --name my-project # same, with agent confirmed ``` -`--password-stdin` reads the token from standard input to keep it out of -your shell history. Generate a PAT from your -[Docker account settings](https://app.docker.com/settings/personal-access-tokens) -with at least **Read** scope. +To run multiple sandboxes against the same workspace, give each a distinct +name: + +```console +$ sbx run claude --name feature ~/my-project +$ sbx run claude --name spike ~/my-project +``` + +## Create without attaching + +[`sbx run`](/reference/cli/sbx/run/) creates the sandbox and attaches you to the +agent. To create a sandbox in the background without attaching: + +```console +$ sbx create --name my-project claude . +``` + +Unlike `run`, `create` requires an explicit workspace path. Attach later with +`sbx run --name`: + +```console +$ sbx run --name my-project +``` + +## Run commands inside a sandbox + +To get a shell inside a running sandbox, use [`sbx exec`](/reference/cli/sbx/exec/): + +```console +$ sbx exec -it bash +``` ## Interactive mode @@ -81,41 +130,39 @@ hosts, and add custom network rules. Press `?` to see all keyboard shortcuts. ## Git workflow -When your workspace is a Git repository, you can choose one of two ways -to share it with a sandbox. You make the choice when you create the -sandbox: +When your workspace is a Git repository, you can share it with a sandbox in one +of two ways: -- **Direct mode (default)** — the agent has read-write access to your +- Direct mode (default): the agent has read-write access to your working tree. Changes the agent makes appear on your host immediately. -- **[Clone mode](#clone-mode) (`--clone`)** — the agent works on a private +- [Clone mode](#clone-mode) (`--clone`): the agent works on a private Git clone inside the sandbox, with your host repository mounted read-only. The sandbox exposes its clone as a Git remote on your host, so you fetch the agent's commits the same way you'd fetch from any other remote. -For a comparison of approaches and step-by-step recipes, see +For a comparison of approaches and workflow recipes, see [Workflow patterns](workflows.md#git-workflows). For the security model behind each mode, see [Workspace isolation](security/isolation.md#workspace-isolation). ### Direct mode (default) -The agent edits your working tree directly. Stage, commit, and push as you -normally would. If you run multiple agents on the same repository at the -same time, they may step on each other's changes — use -[clone mode](#clone-mode) to give each agent its own isolated workspace. +The agent edits your working tree directly. Stage, commit, and push from the +host as you normally would. If you run multiple agents on the same repository at +the same time, use [clone mode](#clone-mode) to give each agent an isolated +workspace. ### Clone mode 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. +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` -> flag used in earlier versions. If your CLI doesn't recognize `--clone`, -> update to the latest version. +```console +$ git fetch sandbox- +``` ```console $ sbx run --clone claude @@ -129,31 +176,10 @@ $ sbx run --name my-sandbox ``` The clone follows whichever ref your host repository has checked out at -create time. No new branch is created automatically. - -> [!NOTE] -> Clone mode is fixed at create time. To switch an existing sandbox to -> clone mode, remove it and recreate it with `sbx create --clone`. +create time. No branch is created automatically. -The CLI copies the Git remotes from your host repository (`origin`, -`upstream`, and so on) into the in-sandbox clone. The agent can push to -your fork directly using the same remote names. Local-path remotes -(`file://` URLs, filesystem paths) aren't copied, since they aren't -reachable from inside the sandbox. - -#### Sandbox lifecycle and the Git remote - -The Git daemon that exposes the in-sandbox clone runs as part of the -sandbox itself. It's only reachable while the sandbox is running: - -- `sbx stop` shuts down the daemon. `git fetch sandbox-` fails until - the sandbox starts again. -- Restarting the sandbox assigns a new ephemeral port to the daemon. The - CLI updates the `sandbox-` remote URL in your host repository's - Git config automatically, so fetching continues to work without manual - reconfiguration. -- `sbx rm` removes the sandbox, the daemon, the published port, and the - `sandbox-` remote entry from your host repository. +Clone mode is fixed at create time. To switch an existing sandbox to clone mode, +remove it and recreate it with `sbx create --clone`. > [!WARNING] > Removing a clone-mode sandbox drops the in-sandbox clone along with it. @@ -161,8 +187,6 @@ sandbox itself. It's only reachable while the sandbox is running: > to an upstream remote are lost. `sbx rm` prints a warning before > deleting a clone-mode sandbox — review it before confirming. -#### Restrictions - Clone mode requires a Git repository as the primary workspace, and is rejected at create time in two cases: @@ -171,66 +195,6 @@ rejected at create time in two cases: read-only bind mount can't resolve the worktree's `.git` pointer file. Run `sbx create --clone` from the main repository checkout instead. -You can also create a Git worktree yourself and run an agent inside it -without `--clone`, but the sandbox won't have access to the `.git` -directory in the parent repository, so the agent can't use Git at all. -See [Host worktree](workflows.md#host-worktree) in Workflow patterns. - -## Reconnecting and naming - -Sandboxes persist after the agent exits. Running the same workspace path again -reconnects to the existing sandbox rather than creating a new one: - -```console -$ sbx run claude ~/my-project # creates sandbox -$ sbx run claude ~/my-project # reconnects to same sandbox -``` - -Use `--name` to give a sandbox an explicit identity: - -```console -$ sbx run claude --name my-project -``` - -Once a named sandbox exists, `--name` is how you re-attach to it — from any -working directory, with or without the agent positional: - -```console -$ sbx run --name my-project # re-attaches from anywhere -$ sbx run claude --name my-project # same, with agent confirmed -``` - -Re-running a command that previously created a sandbox reconnects to it rather -than returning an error, so you can up-arrow and re-enter a session without -first looking up the sandbox name. - -To run multiple sandboxes against the same workspace — for example, one for a -feature branch and one for exploratory changes — give each a distinct name: - -```console -$ sbx run claude --name feature ~/my-project -$ sbx run claude --name spike ~/my-project -``` - -Both sandboxes share the same workspace but are otherwise independent. - -## Creating without attaching - -[`sbx run`](/reference/cli/sbx/run/) creates the sandbox and attaches you to -the agent. To create a sandbox in the background without attaching: - -```console -$ sbx create --name my-project claude . -``` - -Unlike `run`, `create` requires an explicit workspace path. It uses direct -mode by default, or pass `--clone` for [clone mode](#clone-mode). Attach -later with `sbx run --name`: - -```console -$ sbx run --name my-project -``` - ## Multiple workspaces You can mount extra directories into a sandbox alongside the main workspace. @@ -270,28 +234,13 @@ $ sbx cp ./src/ my-sandbox:/home/user/src One side of the copy must use `SANDBOX:PATH`. Copying directly between two sandboxes isn't supported. -## Installing dependencies and using Docker - -Ask the agent to install what's needed — it has sudo access, and installed -packages persist for the sandbox's lifetime. For teams or repeated setups, -see [Customize](customize/) for reusable templates and declarative kits. - -Agents can also build Docker images, run containers, and use -[Compose](/manuals/compose/_index.md). Everything runs inside the sandbox's private Docker -daemon, so containers started by the agent never appear in your host's -`docker ps`. When you remove the sandbox, all images, containers, and volumes -inside it are deleted with it. - -## Accessing services in the sandbox +## Publish ports Sandboxes are [network-isolated](security/isolation.md) — your browser or local tools can't reach a server running inside one by default. Use [`sbx ports`](/reference/cli/sbx/ports/) to forward traffic from your host into a running sandbox. -The common case: an agent has started a dev server or API, and you want to open -it in your browser or run tests against it. - ```console $ sbx ports my-sandbox --publish 8080:3000 # host 8080 → sandbox port 3000 $ open http://localhost:8080 @@ -304,8 +253,8 @@ $ sbx ports my-sandbox --publish 3000 # ephemeral host port $ sbx ports my-sandbox # check which port was assigned ``` -`sbx ls` shows active port mappings alongside each sandbox, and `sbx ports` -lists them in detail: +`sbx ls` shows active port mappings alongside each sandbox. `sbx ports` lists +them in detail. ```console $ sbx ls @@ -319,64 +268,10 @@ To stop forwarding a port: $ sbx ports my-sandbox --unpublish 8080:3000 ``` -For a service to be reachable, it must listen on all interfaces inside the -sandbox, not only `127.0.0.1`. Bind it to `0.0.0.0` for IPv4 or `[::]` for both -IPv4 and IPv6; most dev servers need a flag like `--host 0.0.0.0` to do this. On -the host, `--publish` listens on both `127.0.0.1` and `::1`, so a client -resolving `localhost` might pick IPv6 and fail with "connection reset by peer" -if the sandboxed service only listens on IPv4 — even when -`http://127.0.0.1:/` works. To fix that, bind the service to `[::]`, or -pin the published port to one family with `--publish 8080:3000/tcp4` or `/tcp6`. - -Published ports survive restarts: `sbx` re-publishes them when the sandbox or -the daemon restarts. Explicit host ports are reused, while a port published with -an OS-assigned host port (such as `--publish 3000`) gets a new host port on each -start, so check `sbx ports my-sandbox` to find it. If an explicit host port is -already in use at restart, the CLI or the dashboard prompts you to choose -another. Removing the sandbox releases its ports. - You can't publish ports at create time — there's no `--publish` flag on -`sbx run` or `sbx create`, so publish them once the sandbox is running. To stop -forwarding, `--unpublish 8080:3000` removes a single mapping, and -`--unpublish 3000` removes every host port mapped to sandbox port 3000. - -## Accessing host services from a sandbox - -Services running on your host are reachable from inside a sandbox using the -hostname `host.docker.internal`. -Use this instead of `127.0.0.1` or your machine's local network IP address, -which are not reachable from inside the sandbox. - -The sandbox proxy translates `host.docker.internal` to `localhost` before -forwarding the request, so you must add the `localhost` address with the -specific port to your network policy allowlist: - -```console -$ sbx policy allow network localhost:11434 -``` - -Then use `host.docker.internal` in any configuration or request that points at -the host service. For example, to verify connectivity from a sandbox shell: - -```console -$ curl http://host.docker.internal:11434 -``` - -## Rolling out to a team - -When rolling sandboxes out across a team, two features handle different -needs: - -- [Custom templates and kits](customize/) let you package reusable agent - configurations, MCP servers, base images, and per-project policies. Every - developer pulls them down with their workspace. -- [Organization governance](governance/org.md) lets admins define - network and filesystem rules that apply across every developer's sandboxes - and take precedence over local policy. - Available on a separate paid subscription. - -Customization gives developers shared starting points. Governance gives -admins centralized enforcement. +`sbx run` or `sbx create`, so publish them once the sandbox is running. For +dev server and host-service recipes, see +[Local services](workflows.md#local-services). ## What persists @@ -384,4 +279,4 @@ While a sandbox exists, installed packages, Docker images, configuration changes, and command history all persist across stops and restarts. When you remove a sandbox, everything inside is deleted — only your workspace files remain on your host. To preserve a configured environment, create a -[custom template](customize/templates.md). +[custom template](customize/templates.md) or use a [kit](customize/kits.md). diff --git a/content/manuals/ai/sandboxes/workflows.md b/content/manuals/ai/sandboxes/workflows.md index da19a9271a1b..1de3477ae845 100644 --- a/content/manuals/ai/sandboxes/workflows.md +++ b/content/manuals/ai/sandboxes/workflows.md @@ -2,10 +2,14 @@ title: Workflow patterns linkTitle: Workflows weight: 30 -description: Common workflow patterns for Docker Sandboxes, covering git strategies, authenticated tools, commit signing, and CI integration. -keywords: docker sandboxes, sbx, workflows, clone mode, git, branches, commit signing, github cli, ci, headless +description: Workflow patterns for Docker Sandboxes, covering git strategies, local services, authenticated tools, commit signing, and CI integration. +keywords: docker sandboxes, sbx, workflows, clone mode, git, branches, commit signing, github cli, local services, ci, headless --- +Use this page when you need to choose an approach for a specific way of working +with sandboxes. For command syntax and lifecycle basics, see +[Usage](usage.md). + ## Git workflows Sandboxes support three approaches for working with Git repositories. The @@ -68,10 +72,27 @@ the clone. > [!NOTE] > `--clone` is a create-time flag and cannot be changed on an existing -> sandbox. If you need to run additional non-clone sandboxes for the same -> repository, you would have to remove the clone-mode sandbox first. -> Keep a clone-mode sandbox running across multiple tasks rather than -> recreating it per task. +> sandbox. To change a sandbox from clone mode to direct mode, remove and +> recreate it. To run both modes against the same repository, create separate +> sandboxes with distinct names. + +#### Sandbox remote behavior + +The CLI copies Git remotes from your host repository, such as `origin` and +`upstream`, into the in-sandbox clone. Local-path remotes, such as `file://` +URLs and filesystem paths, aren't copied because they aren't reachable from +inside the sandbox. + +The Git daemon that exposes the in-sandbox clone runs as part of the sandbox. +It's only reachable while the sandbox is running: + +- `sbx stop` shuts down the daemon. `git fetch sandbox-` fails until the + sandbox starts again. +- Restarting the sandbox assigns another ephemeral port to the daemon. The CLI + updates the `sandbox-` remote URL in your host repository's Git config, + so fetching continues without manual reconfiguration. +- `sbx rm` removes the sandbox, the daemon, the published port, and the + `sandbox-` remote entry from your host repository. #### Single task @@ -120,7 +141,7 @@ the clone. behavior: ```markdown - Always start each task on a new git branch before making changes. + Always start each task on its own git branch before making changes. ``` 3. Fetch all branches when the agents are done: @@ -167,6 +188,109 @@ yourself after reviewing the changes. $ gh pr create ``` +## Build and test inside a sandbox + +Agents have sudo access inside the sandbox, so they can install packages, +start databases, run test dependencies, and prepare the environment they need. +Installed packages persist for the sandbox's lifetime. For repeated setup, use +[Customize](customize/) to package the environment as a template or kit. + +Agents can also build Docker images, run containers, and use +[Compose](/manuals/compose/_index.md). Everything runs inside the sandbox's +private Docker daemon, so containers started by the agent never appear in your +host's `docker ps`. When you remove the sandbox, all images, containers, and +volumes inside it are deleted with it. + +This pattern works well for tasks where the agent needs to run the project's +test suite or inspect a service it started. If you need to reach that service +from your host, publish a port after the sandbox is running. + +## Local services + +Use this workflow when a sandboxed agent starts a dev server, or when the agent +needs to call a service running on your host. + +### Accessing services in the sandbox + +Sandboxes are [network-isolated](security/isolation.md) — your browser or local +tools can't reach a server running inside one by default. Use +[`sbx ports`](/reference/cli/sbx/ports/) to forward traffic from your host into +a running sandbox. + +The common case: an agent has started a dev server or API, and you want to open +it in your browser or run tests against it. + +```console +$ sbx ports my-sandbox --publish 8080:3000 # host 8080 → sandbox port 3000 +$ open http://localhost:8080 +``` + +To let the OS pick a free host port instead of choosing one yourself: + +```console +$ sbx ports my-sandbox --publish 3000 # ephemeral host port +$ sbx ports my-sandbox # check which port was assigned +``` + +`sbx ls` shows active port mappings alongside each sandbox, and `sbx ports` +lists them in detail: + +```console +$ sbx ls +SANDBOX AGENT STATUS PORTS WORKSPACE +my-sandbox claude running 127.0.0.1:8080->3000/tcp /home/user/proj +``` + +To stop forwarding a port: + +```console +$ sbx ports my-sandbox --unpublish 8080:3000 +``` + +For a service to be reachable, it must listen on all interfaces inside the +sandbox, not only `127.0.0.1`. Bind it to `0.0.0.0` for IPv4 or `[::]` for both +IPv4 and IPv6. Most dev servers need a flag like `--host 0.0.0.0` to do this. +On the host, `--publish` listens on both `127.0.0.1` and `::1`, so a client +resolving `localhost` might pick IPv6 and fail with "connection reset by peer" +if the sandboxed service only listens on IPv4, even when +`http://127.0.0.1:/` works. To fix that, bind the service to `[::]`, or +pin the published port to one family with `--publish 8080:3000/tcp4` or +`/tcp6`. + +Published ports survive restarts: `sbx` re-publishes them when the sandbox or +the daemon restarts. Explicit host ports are reused, while a port published with +an OS-assigned host port, such as `--publish 3000`, gets a different host port +on each start. Check `sbx ports my-sandbox` to find it. If an explicit host port +is already in use at restart, the CLI or the dashboard prompts you to choose +another. Removing the sandbox releases its ports. + +You can't publish ports at create time — there's no `--publish` flag on +`sbx run` or `sbx create`, so publish them once the sandbox is running. To stop +forwarding, `--unpublish 8080:3000` removes a single mapping, and +`--unpublish 3000` removes every host port mapped to sandbox port 3000. + +### Accessing host services from a sandbox + +Services running on your host are reachable from inside a sandbox using the +hostname `host.docker.internal`. Use this instead of `127.0.0.1` or your +machine's local network IP address, which are not reachable from inside the +sandbox. + +The sandbox proxy translates `host.docker.internal` to `localhost` before +forwarding the request, so you must add the `localhost` address with the +specific port to your network policy allowlist: + +```console +$ sbx policy allow network localhost:11434 +``` + +Then use `host.docker.internal` in any configuration or request that points at +the host service. For example, to verify connectivity from a sandbox shell: + +```console +$ curl http://host.docker.internal:11434 +``` + ## Commit signing Sandboxes forward your host SSH agent into the sandbox, so the agent can @@ -214,7 +338,7 @@ proxy or via SSH agent forwarding. > [!NOTE] > The `-g` flag stores a secret globally so all future sandboxes can use it. > Sandboxes that already exist when you run `sbx secret set -g` do not -> receive the new value. To update a running sandbox, scope the secret to +> receive the updated value. To update a running sandbox, scope the secret to > it directly: `sbx secret set `. ### GitHub CLI @@ -332,7 +456,7 @@ $ git fetch sandbox-ci-task $ sbx rm ci-task ``` -Agent credentials (API keys, GitHub token) can be pre-configured as global +Agent credentials (API keys, GitHub token) can be preconfigured as global secrets so they're available to any sandbox the CI runner creates. If the relevant environment variables are already set in the CI environment (see the [built-in services table](security/credentials.md#built-in-services) for which @@ -348,3 +472,22 @@ CI provider's secret store, use `-t`. For example, in a GitHub Actions step: ```yaml - run: sbx secret set -g anthropic -t "${{ secrets.ANTHROPIC_API_KEY }}" ``` + +## Share setup across a team + +When several people use sandboxes on the same project, separate repeatable +environment setup from policy enforcement. + +Use [custom templates and kits](customize/) for project-level setup: agent +configurations, MCP servers, base images, setup scripts, and per-project +defaults. Version kit specs and template definitions with the project, and +publish reusable template images to your registry. This gives each developer the +same starting environment. + +Use [organization governance](governance/org.md) for rules that admins need to +apply across developers, such as network and filesystem policies. Organization +rules are managed in the Docker Admin Console, take precedence over local +policy, and require a separate paid subscription. + +You can use both. Templates and kits describe the development environment; +governance defines the boundaries it runs within. From 0392cffc95c402e3f776abc71646ee77e59cd462 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 14 Jul 2026 12:50:47 +0000 Subject: [PATCH 2/2] 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. --- content/manuals/ai/sandboxes/usage.md | 75 ++++++++++----------------- 1 file changed, 26 insertions(+), 49 deletions(-) diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index da3b45410abf..5b5008b3c721 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -128,41 +128,24 @@ to switch between the sandboxes panel and the network panel. From the network panel you can browse connection logs, allow or block specific hosts, and add custom network rules. Press `?` to see all keyboard shortcuts. -## Git workflow - -When your workspace is a Git repository, you can share it with a sandbox in one -of two ways: - -- Direct mode (default): the agent has read-write access to your - working tree. Changes the agent makes appear on your host immediately. -- [Clone mode](#clone-mode) (`--clone`): the agent works on a private - Git clone inside the sandbox, with your host repository mounted - read-only. The sandbox exposes its clone as a Git remote on your host, - so you fetch the agent's commits the same way you'd fetch from any - other remote. - -For a comparison of approaches and workflow recipes, see -[Workflow patterns](workflows.md#git-workflows). For the security model -behind each mode, see -[Workspace isolation](security/isolation.md#workspace-isolation). +## Git workspace modes -### Direct mode (default) +When your primary workspace is a Git repository, choose how the sandbox receives +it when you create the sandbox: -The agent edits your working tree directly. Stage, commit, and push from the -host as you normally would. If you run multiple agents on the same repository at -the same time, use [clone mode](#clone-mode) to give each agent an isolated -workspace. +- Direct mode is the default. The agent has read-write access to your working + tree, and changes appear on your host immediately. +- [Clone mode](#clone-mode) uses `--clone`. The agent works in a private Git + clone inside the sandbox, and your host repository is mounted read-only. -### Clone mode +For guidance on branch strategy, fetching work from a sandbox, and parallel +agent workflows, see [Git workflows](workflows.md#git-workflows). For the +security model behind each mode, see +[Workspace isolation](security/isolation.md#workspace-isolation). -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: +### Clone mode -```console -$ git fetch sandbox- -``` +To create a clone-mode sandbox, pass `--clone` when you run or create it: ```console $ sbx run --clone claude @@ -175,25 +158,19 @@ $ sbx create --clone --name my-sandbox claude . $ sbx run --name my-sandbox ``` -The clone follows whichever ref your host repository has checked out at -create time. No branch is created automatically. - -Clone mode is fixed at create time. To switch an existing sandbox to clone mode, -remove it and recreate it with `sbx create --clone`. - -> [!WARNING] -> Removing a clone-mode sandbox drops the in-sandbox clone along with it. -> Any commits you haven't fetched (`git fetch sandbox-`) or pushed -> to an upstream remote are lost. `sbx rm` prints a warning before -> deleting a clone-mode sandbox — review it before confirming. - -Clone mode requires a Git repository as the primary workspace, and is -rejected at create time in two cases: - -- `--clone` on a non-Git workspace. Omit `--clone` for non-Git workspaces. -- `--clone` from inside a Git worktree (other than the main one). The - read-only bind mount can't resolve the worktree's `.git` pointer file. - Run `sbx create --clone` from the main repository checkout instead. +Clone mode has a few create-time constraints: + +- Clone mode is fixed at create time. To switch an existing sandbox to clone + mode, remove it and recreate it with `sbx create --clone`. +- The clone follows whichever ref your host repository has checked out at create + time. No branch is created automatically. +- The primary workspace must be a Git repository. Omit `--clone` for non-Git + workspaces. +- Clone mode is rejected from inside a Git worktree other than the main one. The + read-only bind mount can't resolve the worktree's `.git` pointer file. Run + `sbx create --clone` from the main repository checkout instead. +- Removing a clone-mode sandbox drops the in-sandbox clone. Fetch or push any + commits you want to keep before you remove it. ## Multiple workspaces