nprasad2077/docker-docs
1
0 Fork 0
mirror of https://github.com/docker/docs.git synced 2026-11-04 10:01:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #25561 from dvdksn/codex/refactor-sbx-usage-workflows

Browse Source 
Clarify sandbox usage and workflow docs
This commit is contained in:
David Karlsson authored and GitHub committed 2026-07-15 20:51:44 +02:00
1 parent 38cfd38b24
commit 4d30fabe3c
8 files changed
+262 -248
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

content/guides/claude-code-sandbox-model-runner.md
+1 -1
View File
@@ -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
content/manuals/ai/sandboxes/_index.md
+1 -1
View File
@@ -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
content/manuals/ai/sandboxes/agents/claude-code.md
+3 -3
View File
@@ -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-<sandbox-name>
$ git diff main..sandbox-<sandbox-name>/<branch>
```
See [Git workflow](../usage.md#git-workflow) for clone-mode details.
See [Git workflows](../workflows.md#git-workflows) for clone-mode details.
## Base image
content/manuals/ai/sandboxes/get-started.md
+5 -6
View File
@@ -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.
content/manuals/ai/sandboxes/security/isolation.md
+1 -1
View File
@@ -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)
content/manuals/ai/sandboxes/troubleshooting.md
+1 -1
View File
@@ -117,7 +117,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
content/manuals/ai/sandboxes/usage.md
+98 -226
View File
@@ -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,14 +40,7 @@ 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:
```console
$ sbx exec -it <sandbox-name> bash
```
If you need a clean slate, remove the sandbox and re-run:
If you need a clean slate, remove the sandbox and run it again:
```console
$ sbx stop my-sandbox
@@ -41,19 +48,61 @@ $ sbx rm my-sandbox
$ sbx run claude
```
## Non-interactive login
## Reconnect and name sandboxes
For CI environments and scripts where a browser is not available, use a
Docker Personal Access Token (PAT) with `--username` and `--password-stdin`:
Sandboxes persist after the agent exits. Running the same workspace path again
reconnects to the existing sandbox rather than creating another sandbox:
```console
$ echo "$DOCKER_PAT" | sbx login --username <your-docker-id> --password-stdin
$ sbx run claude ~/my-project # creates sandbox
$ sbx run claude ~/my-project # reconnects to same sandbox
```
`--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.
Use `--name` to give a sandbox an explicit identity:
```console
$ sbx run claude --name my-project
```
Once a named sandbox exists, use `--name` to 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
```
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 <sandbox-name> bash
```
## Interactive mode
@@ -79,43 +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
## Git workspace modes
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 primary workspace is a Git repository, choose how the sandbox receives
it when you create the sandbox:
- **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.
- 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.
For a comparison of approaches and step-by-step recipes, see
[Workflow patterns](workflows.md#git-workflows). For the security model
behind each mode, see
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).
### 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.
### 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.
> [!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.
To create a clone-mode sandbox, pass `--clone` when you run or create it:
```console
$ sbx run --clone claude
@@ -128,108 +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 new branch is created automatically.
Clone mode has a few create-time constraints:
> [!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`.
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-<name>` fails until
the sandbox starts again.
- Restarting the sandbox assigns a new ephemeral port to the daemon. The
CLI updates the `sandbox-<name>` 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-<name>` remote entry from your host repository.
> [!WARNING]
> Removing a clone-mode sandbox drops the in-sandbox clone along with it.
> Any commits you haven't fetched (`git fetch sandbox-<name>`) or pushed
> 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:
- `--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.
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
```
- 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
@@ -270,28 +211,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 +230,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 +245,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:<port>/` 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 +256,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).
content/manuals/ai/sandboxes/workflows.md
+152 -9
View File
@@ -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-<name>` fails until the
sandbox starts again.
- Restarting the sandbox assigns another ephemeral port to the daemon. The CLI
updates the `sandbox-<name>` 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-<name>` 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:<port>/` 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 <sandbox-name> <service>`.
### 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.