mirror of
https://github.com/docker/docs.git
synced 2026-11-04 10:01:00 +00:00
docs: reorganize Docker Sandboxes content
This commit is contained in:
51 files changed
+771
-699
No files matched your search
@@ -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/workflows.md#accessing-host-services-from-a-sandbox).
|
||||
[Accessing host services from a sandbox](../manuals/ai/sandboxes/workflows/development.md#accessing-host-services-from-a-sandbox).
|
||||
|
||||
## Step 3: Create a Claude Code sandbox
|
||||
|
||||
@@ -111,7 +111,7 @@ You don't need to set an Anthropic API key or run `sbx secret set
|
||||
anthropic`. Docker Model Runner doesn't authenticate the local endpoint,
|
||||
and the sandbox proxy only injects credentials for requests bound for
|
||||
`api.anthropic.com`. See
|
||||
[Credentials](../manuals/ai/sandboxes/security/credentials.md) for the full
|
||||
[Credentials](../manuals/ai/sandboxes/configuration/credentials.md) for the full
|
||||
list of services the proxy authenticates. For more ways to set variables, see
|
||||
[Set environment variables](../manuals/ai/sandboxes/usage.md#set-environment-variables).
|
||||
|
||||
|
||||
@@ -40,18 +40,18 @@ jump to the [usage guide](usage.md) for basic commands.
|
||||
## Learn more
|
||||
|
||||
- [Agents](agents/) — supported agents and per-agent configuration
|
||||
- [Workflows](workflows/) — patterns for Git, local development,
|
||||
authentication, agent skills, and automation
|
||||
- [Configuration](configuration/) — manage credentials, declare project
|
||||
environments, turn on GPU passthrough, and configure an upstream proxy
|
||||
- [Integrations](integrations/) — connect editors and apps like VS Code and
|
||||
Cursor to a sandbox over SSH
|
||||
- [MCP gateway](mcp-gateway.md) — register MCP servers and connect them to
|
||||
sandboxed agents
|
||||
- [Customize](customize/) — reusable templates and declarative kits for
|
||||
extending or tailoring sandboxes
|
||||
- [GPU passthrough](gpu-passthrough.md) — build the NVIDIA driver bundle and
|
||||
run GPU-accelerated workloads in a sandbox
|
||||
- [Architecture](architecture.md) — microVM isolation, workspace mounting,
|
||||
networking
|
||||
- [Upstream proxy](upstream-proxy.md) — route sandbox and daemon traffic through
|
||||
a corporate proxy, PAC file, or your OS system proxy
|
||||
- [Security](security/) — isolation model, credential handling, and
|
||||
network policies
|
||||
- [CLI reference](/reference/cli/sbx/) — full list of `sbx` commands and options
|
||||
|
||||
@@ -12,11 +12,11 @@ Docker Sandboxes runs the following agents out of the box:
|
||||
- [Codex](codex/)
|
||||
- [Copilot](copilot/)
|
||||
- [Cursor](cursor/)
|
||||
- [Docker Agent](docker-agent/)
|
||||
- [Droid](droid/)
|
||||
- [Gemini](gemini/)
|
||||
- [Kiro](kiro/)
|
||||
- [OpenCode](opencode/)
|
||||
- [Docker Agent](docker-agent/)
|
||||
- [Shell](shell/) — agent-less sandbox for manual setup or testing
|
||||
|
||||
Want to pre-install tools or customize an agent's environment?
|
||||
|
||||
@@ -32,7 +32,7 @@ prompt from a file with `-- "$(cat prompt.txt)"`.
|
||||
Claude Code requires either an Anthropic API key or a Claude subscription.
|
||||
|
||||
**API key**: Store your key using
|
||||
[stored secrets](../security/credentials.md#stored-secrets):
|
||||
[stored secrets](../configuration/credentials.md#stored-secrets):
|
||||
|
||||
```console
|
||||
$ sbx secret set anthropic
|
||||
@@ -84,7 +84,7 @@ for available options.
|
||||
|
||||
Claude Code's [agents view](https://code.claude.com/docs/en/agent-view)
|
||||
starts background sessions that run tasks in parallel. Pair it with
|
||||
[clone mode](../workflows.md#clone-mode) to keep their changes inside the
|
||||
[clone mode](../workflows/git.md#clone-mode) to keep their changes inside the
|
||||
sandbox:
|
||||
|
||||
```console
|
||||
@@ -115,7 +115,7 @@ $ git fetch sandbox-<sandbox-name>
|
||||
$ git diff main..sandbox-<sandbox-name>/<branch>
|
||||
```
|
||||
|
||||
See [Git workflows](../workflows.md#git-workflows) for clone-mode details.
|
||||
See [Git workflows](../workflows/git.md) for clone-mode details.
|
||||
|
||||
## Base image
|
||||
|
||||
|
||||
@@ -46,13 +46,13 @@ in your OS keychain. The OAuth flow runs on the host, not inside the sandbox,
|
||||
so browser-based authentication works without any extra setup.
|
||||
|
||||
**API key**: Store your OpenAI API key using
|
||||
[stored secrets](../security/credentials.md#stored-secrets):
|
||||
[stored secrets](../configuration/credentials.md#stored-secrets):
|
||||
|
||||
```console
|
||||
$ sbx secret set openai
|
||||
```
|
||||
|
||||
See [Credentials](../security/credentials.md) for more details.
|
||||
See [Credentials](../configuration/credentials.md) for more details.
|
||||
|
||||
## Configuration
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ $ sbx run copilot
|
||||
## Authentication
|
||||
|
||||
Copilot requires a GitHub token with Copilot access. Store your token using
|
||||
[stored secrets](../security/credentials.md#stored-secrets):
|
||||
[stored secrets](../configuration/credentials.md#stored-secrets):
|
||||
|
||||
```console
|
||||
$ sbx secret set github --command 'gh auth token'
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Cursor
|
||||
weight: 33
|
||||
weight: 40
|
||||
description: |
|
||||
Use Cursor in Docker Sandboxes with API key or proxy-managed OAuth
|
||||
authentication.
|
||||
@@ -32,7 +32,7 @@ $ sbx run cursor
|
||||
Cursor supports two authentication methods: an API key or OAuth.
|
||||
|
||||
**API key**: Store your Cursor API key using
|
||||
[stored secrets](../security/credentials.md#stored-secrets):
|
||||
[stored secrets](../configuration/credentials.md#stored-secrets):
|
||||
|
||||
```console
|
||||
$ sbx secret set cursor
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Docker Agent
|
||||
weight: 70
|
||||
weight: 50
|
||||
description: |
|
||||
Use Docker Agent in Docker Sandboxes with multi-provider authentication
|
||||
supporting OpenAI, Anthropic, and more.
|
||||
@@ -23,7 +23,7 @@ The workspace parameter defaults to the current directory, so
|
||||
## Authentication
|
||||
|
||||
Docker Agent supports multiple providers. Store keys for the providers you want
|
||||
to use with [stored secrets](../security/credentials.md#stored-secrets):
|
||||
to use with [stored secrets](../configuration/credentials.md#stored-secrets):
|
||||
|
||||
```console
|
||||
$ sbx secret set openai
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Droid
|
||||
weight: 35
|
||||
weight: 60
|
||||
description: |
|
||||
Use Droid in Docker Sandboxes with API key or OAuth authentication.
|
||||
keywords: docker sandboxes, droid, factory, ai agent, sbx
|
||||
@@ -34,7 +34,7 @@ where you supply a model provider key, Factory manages model access through
|
||||
your Factory account.
|
||||
|
||||
**API key**: Store your Factory API key using
|
||||
[stored secrets](../security/credentials.md#stored-secrets):
|
||||
[stored secrets](../configuration/credentials.md#stored-secrets):
|
||||
|
||||
```console
|
||||
$ sbx secret set droid
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Gemini
|
||||
weight: 40
|
||||
weight: 70
|
||||
description: |
|
||||
Use Google Gemini in Docker Sandboxes with proxy-managed authentication and
|
||||
API key configuration.
|
||||
@@ -32,7 +32,7 @@ $ sbx run gemini
|
||||
Gemini requires either a Google API key or a Google account with Gemini access.
|
||||
|
||||
**API key**: Store your key using
|
||||
[stored secrets](../security/credentials.md#stored-secrets):
|
||||
[stored secrets](../configuration/credentials.md#stored-secrets):
|
||||
|
||||
```console
|
||||
$ sbx secret set google
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Kiro
|
||||
weight: 50
|
||||
weight: 80
|
||||
description: |
|
||||
Use Kiro in Docker Sandboxes with device flow authentication for interactive
|
||||
AI-assisted development.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: OpenCode
|
||||
weight: 60
|
||||
weight: 90
|
||||
description: |
|
||||
Use OpenCode in Docker Sandboxes with multi-provider authentication and TUI
|
||||
interface for AI development.
|
||||
@@ -33,7 +33,7 @@ preferred LLM provider and interact with the agent.
|
||||
## Authentication
|
||||
|
||||
OpenCode supports multiple providers. Store keys for the providers you want to
|
||||
use with [stored secrets](../security/credentials.md#stored-secrets):
|
||||
use with [stored secrets](../configuration/credentials.md#stored-secrets):
|
||||
|
||||
```console
|
||||
$ sbx secret set openai
|
||||
@@ -52,7 +52,7 @@ available credentials and offers those providers in the TUI.
|
||||
|
||||
OpenCode Zen API keys aren't part of the built-in OpenCode credentials that
|
||||
`sbx secret set` supports. To use an OpenCode Zen API key, store it as a
|
||||
[custom secret](../security/credentials.md#custom-secrets):
|
||||
[custom secret](../configuration/credentials.md#custom-secrets):
|
||||
|
||||
Set the `OPENCODE_API_KEY` environment variable on the host, then store it:
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Shell
|
||||
weight: 90
|
||||
weight: 100
|
||||
description: Run an agent-less sandbox with a Bash login shell for manual setup, testing custom agent implementations, or inspecting a running environment.
|
||||
keywords: sandboxes, sbx, shell, agent, manual setup, testing
|
||||
---
|
||||
@@ -33,7 +33,7 @@ $ sbx run shell -- -c "echo hi" # runs bash -l -c "echo hi"
|
||||
|
||||
When the first argument is a bare word, it replaces `-l` instead.
|
||||
|
||||
Store credentials using [stored secrets](../security/credentials.md#stored-secrets)
|
||||
Store credentials using [stored secrets](../configuration/credentials.md#stored-secrets)
|
||||
before running the sandbox. The proxy injects them into outbound API requests;
|
||||
credentials are never stored inside the VM:
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Architecture
|
||||
weight: 70
|
||||
weight: 100
|
||||
description: Technical architecture of Docker Sandboxes; workspace mounting, storage, networking, and sandbox lifecycle.
|
||||
keywords: docker sandboxes, architecture, microVM, workspace mounting, sandbox lifecycle
|
||||
---
|
||||
@@ -33,7 +33,7 @@ agent state and history, and workspace changes.
|
||||
|
||||
Each sandbox maintains its own Docker daemon state, image cache, and package
|
||||
installations. Multiple sandboxes don't share images or layers. The
|
||||
[shared agent skills store](workflows.md#share-agent-skills) is an exception:
|
||||
[shared agent skills store](workflows/agent-skills.md) is an exception:
|
||||
supported agents mount the same host-side store read-write unless you opt out
|
||||
when creating the sandbox.
|
||||
|
||||
@@ -56,7 +56,7 @@ All outbound TCP traffic from the sandbox routes through a proxy on your host.
|
||||
Agents use a forward proxy for HTTP and HTTPS; other TCP traffic is forwarded
|
||||
transparently. Both paths enforce
|
||||
[network access policies](governance/access-controls/network.md). The forward
|
||||
proxy also handles [credential injection](security/credentials.md). See
|
||||
proxy also handles [credential injection](configuration/credentials.md). See
|
||||
[Network isolation](security/isolation.md#network-isolation) for how this
|
||||
works and [Default security posture](security/defaults.md) for what is
|
||||
allowed out of the box.
|
||||
@@ -74,7 +74,7 @@ By default, both sandbox traffic and the daemon's own traffic follow your OS
|
||||
system proxy, so this usually works without any configuration. To set a proxy
|
||||
explicitly — with a proxy URL, a PAC file, a SOCKS5 proxy, or separate settings
|
||||
for sandbox and daemon traffic — see
|
||||
[Configure an upstream proxy](upstream-proxy.md). Upstream proxy support is
|
||||
[Configure an upstream proxy](configuration/upstream-proxy.md). Upstream proxy support is
|
||||
experimental and subject to change.
|
||||
|
||||
Only HTTP and HTTPS traffic can be forwarded to an upstream proxy. Other TCP
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Configure Docker Sandboxes
|
||||
linkTitle: Configuration
|
||||
weight: 60
|
||||
description: Configure credentials, project environments, GPU passthrough, and upstream proxy settings for Docker Sandboxes.
|
||||
keywords: docker sandboxes, sbx, configuration, credentials, environment files, gpu passthrough, upstream proxy
|
||||
---
|
||||
|
||||
Configure credentials and how Docker Sandboxes run for a project, host, or
|
||||
network environment. These settings control sandbox creation, authentication,
|
||||
and connectivity. To change the tools and agent configuration inside a
|
||||
sandbox, see [Customize](../customize/).
|
||||
|
||||
- [Credentials](credentials.md) configures API keys, authentication
|
||||
credentials, and registry access for sandboxed agents.
|
||||
- [Environment files](environment-files.md) declare reusable project
|
||||
configuration in `.sbxenv.yaml`.
|
||||
- [GPU passthrough](gpu-passthrough.md) configures a Linux host and sandbox for
|
||||
NVIDIA GPU workloads.
|
||||
- [Upstream proxy](upstream-proxy.md) routes sandbox and daemon traffic through
|
||||
an operating system or corporate proxy.
|
||||
+10
-7
@@ -1,8 +1,11 @@
|
||||
---
|
||||
title: Credentials
|
||||
weight: 20
|
||||
title: Manage credentials
|
||||
linkTitle: Credentials
|
||||
weight: 10
|
||||
description: How Docker Sandboxes handle API keys and authentication credentials for sandboxed agents.
|
||||
keywords: docker sandboxes, credentials, api keys, authentication, proxy, ssh agent, secrets
|
||||
aliases:
|
||||
- /ai/sandboxes/security/credentials/
|
||||
---
|
||||
|
||||
Most agents need an API key for their model provider. An HTTP/HTTPS proxy on
|
||||
@@ -10,7 +13,7 @@ your host intercepts outbound requests from the sandbox, looks up the matching
|
||||
credential on the host, and overwrites the auth header before forwarding. The
|
||||
real credential stays on the host when proxy management is active; the sandbox
|
||||
sees only a sentinel value. See
|
||||
[Trust boundaries](_index.md#trust-boundaries) for how credential isolation
|
||||
[Trust boundaries](../security/_index.md#trust-boundaries) for how credential isolation
|
||||
fits into the broader sandbox security model.
|
||||
|
||||
## How credential injection works
|
||||
@@ -182,7 +185,7 @@ $ sbx secret import openai --force
|
||||
|
||||
Pass `--dry-run` to preview what would be imported without writing anything.
|
||||
Run `sbx secret ls` afterwards to confirm what's stored. For setting up
|
||||
credentials in CI, see [CI and headless use](../workflows.md#ci-and-headless-use).
|
||||
credentials in CI, see [CI and headless use](../workflows/automation.md).
|
||||
|
||||
### Built-in services
|
||||
|
||||
@@ -281,7 +284,7 @@ Use SSH agent forwarding for Git operations over SSH and SSH-based commit
|
||||
signing. The signing key must be loaded in the host SSH agent for sandboxed
|
||||
commit signing to work. Outbound SSH connections are still subject to sandbox
|
||||
network policy. For details, see
|
||||
[Commit signing](../workflows.md#commit-signing).
|
||||
[Commit signing](../workflows/git.md#commit-signing).
|
||||
|
||||
## Custom secrets
|
||||
|
||||
@@ -539,8 +542,8 @@ $ sbx secret rm --sandbox my-sandbox --registry ghcr.io -f
|
||||
appears when the agent starts. See the individual [agent pages](../agents/)
|
||||
for each agent's flow.
|
||||
- If you store credentials in 1Password or AWS Secrets Manager, see
|
||||
[Sourcing credentials from 1Password](../workflows.md#sourcing-credentials-from-1password)
|
||||
and [Sourcing credentials from AWS Secrets Manager](../workflows.md#sourcing-credentials-from-aws-secrets-manager).
|
||||
[Sourcing credentials from 1Password](../workflows/authentication.md#source-credentials-from-1password)
|
||||
and [Sourcing credentials from AWS Secrets Manager](../workflows/authentication.md#source-credentials-from-aws-secrets-manager).
|
||||
|
||||
## Custom templates and placeholder values
|
||||
|
||||
+8
-6
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Sandbox environment files
|
||||
linkTitle: Environment files
|
||||
weight: 35
|
||||
weight: 20
|
||||
description: Use a declarative .sbxenv.yaml file to describe and share your sandbox configuration.
|
||||
keywords:
|
||||
- docker sandboxes
|
||||
@@ -10,6 +10,8 @@ keywords:
|
||||
- environment file
|
||||
- sandbox configuration
|
||||
- declarative
|
||||
aliases:
|
||||
- /ai/sandboxes/sandbox-environments/
|
||||
params:
|
||||
sidebar:
|
||||
badge:
|
||||
@@ -237,10 +239,10 @@ The loader rejects unknown fields and unsupported schema versions.
|
||||
`kits` accepts local directories, ZIP archives, OCI registry references, and
|
||||
Git URLs prefixed with `git+https://` or `git+ssh://`. Kits can install tools,
|
||||
configure the sandbox, and give the agent project-specific instructions. See
|
||||
[Kits](customize/kits.md) for details.
|
||||
[Kits](../customize/kits.md) for details.
|
||||
|
||||
Remote kit sources must match the
|
||||
[kit source allowlist](customize/kits.md#restrict-kit-sources). Docker Hub is
|
||||
[kit source allowlist](../customize/kits.md#restrict-kit-sources). Docker Hub is
|
||||
allowed by default. To use Git kits from `docker/sbx-kits-contrib`, add its
|
||||
source:
|
||||
|
||||
@@ -258,11 +260,11 @@ When specified as a string, `workspace` is the path. Use the object form for
|
||||
clone mode:
|
||||
|
||||
> [!WARNING]
|
||||
> With [direct mount](security/isolation.md#direct-mount-default), the agent can
|
||||
> With [direct mount](../security/isolation.md#direct-mount-default), the agent can
|
||||
> modify every file in a workspace. If an environment file is inside a mounted
|
||||
> workspace, the agent can change the file that controls later `sbx env`
|
||||
> commands. Store environment files outside all direct-mounted workspaces.
|
||||
> [Clone mode](security/isolation.md#clone-mode) protects files in the primary
|
||||
> [Clone mode](../security/isolation.md#clone-mode) protects files in the primary
|
||||
> repository, but additional workspaces remain direct-mounted.
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
@@ -363,7 +365,7 @@ registries:
|
||||
### `mcp`
|
||||
|
||||
The `mcp.servers` list registers servers with the built-in
|
||||
[MCP gateway](mcp-gateway.md) and adds them to the sandbox. MCP registrations
|
||||
[MCP gateway](../mcp-gateway.md) and adds them to the sandbox. MCP registrations
|
||||
are host-global and remain after `sbx env rm`.
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
+3
-1
@@ -3,7 +3,9 @@ title: Enable NVIDIA GPU passthrough
|
||||
linkTitle: GPU passthrough
|
||||
description: Run GPU-accelerated workloads in a sandbox by building and installing the NVIDIA driver bundle for VFIO passthrough.
|
||||
keywords: docker sandboxes, sbx, gpu, gpu passthrough, nvidia, vfio, iommu, driver bundle, cuda
|
||||
weight: 65
|
||||
weight: 30
|
||||
aliases:
|
||||
- /ai/sandboxes/gpu-passthrough/
|
||||
---
|
||||
|
||||
> [!IMPORTANT]
|
||||
+6
-4
@@ -3,7 +3,9 @@ title: Configure an upstream proxy
|
||||
linkTitle: Upstream proxy
|
||||
description: Route sandbox and daemon traffic through a corporate or upstream proxy, including PAC files, SOCKS5, and your OS system proxy.
|
||||
keywords: docker sandboxes, sbx, upstream proxy, corporate proxy, pac, socks5, system proxy, no_proxy, egress, ntlm, kerberos
|
||||
weight: 75
|
||||
weight: 40
|
||||
aliases:
|
||||
- /ai/sandboxes/upstream-proxy/
|
||||
---
|
||||
|
||||
> [!IMPORTANT]
|
||||
@@ -15,7 +17,7 @@ weight: 75
|
||||
|
||||
An upstream proxy is the corporate or network proxy that Docker Sandboxes
|
||||
forwards outbound traffic through on its way to the internet. This is separate
|
||||
from the [network policy](governance/access-controls/network.md), which decides
|
||||
from the [network policy](../governance/access-controls/network.md), which decides
|
||||
_which_ destinations are allowed. The upstream proxy decides _how_ allowed
|
||||
traffic reaches them.
|
||||
|
||||
@@ -164,7 +166,7 @@ platforms, credentials in the proxy URL remain the only option.
|
||||
|
||||
## Related pages
|
||||
|
||||
- [Network isolation](security/isolation.md) — how traffic leaves a sandbox and
|
||||
- [Network isolation](../security/isolation.md) — how traffic leaves a sandbox and
|
||||
the network policy it passes through
|
||||
- [Troubleshooting: API calls fail with a certificate error](troubleshooting.md#api-calls-fail-with-a-certificate-error)
|
||||
- [Troubleshooting: API calls fail with a certificate error](../troubleshooting.md#api-calls-fail-with-a-certificate-error)
|
||||
— installing an internal root CA when your proxy inspects HTTPS traffic
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
title: Customizing sandboxes
|
||||
linkTitle: Customize
|
||||
description: Build reusable sandbox images, extend agents with tools and credentials, and define custom agents using templates and kits.
|
||||
description: Build reusable sandbox images and extend or define agents using templates and kits.
|
||||
keywords: sandboxes, sbx, customize, templates, kits, mixins, custom agents
|
||||
weight: 60
|
||||
weight: 90
|
||||
aliases:
|
||||
- /ai/sandboxes/agents/custom-environments/
|
||||
params:
|
||||
|
||||
@@ -3,7 +3,7 @@ title: Kit examples
|
||||
linkTitle: Examples
|
||||
description: Copy-and-adapt spec.yaml snippets for common mixin and sandbox kit patterns — static files, install commands, shell customization, background services, setup files, Claude Code skills, and agent forks.
|
||||
keywords: sandboxes, sbx, kits, mixins, examples, patterns, skills
|
||||
weight: 25
|
||||
weight: 40
|
||||
---
|
||||
|
||||
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
|
||||
@@ -376,7 +376,7 @@ $ sbx secret set anthropic
|
||||
When you launch the kit for the first time, `sbx` prompts you to approve its
|
||||
inherited Anthropic credentials. Because this is a third-party schema v2 kit,
|
||||
`sbx` records your approval as a
|
||||
[credential binding](../security/credentials.md#credential-bindings). The
|
||||
[credential binding](../configuration/credentials.md#credential-bindings). The
|
||||
sandbox receives a sentinel value, and the proxy injects the real API key into
|
||||
requests to the domains declared by the kit.
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ title: Kit spec reference
|
||||
linkTitle: Spec reference
|
||||
description: Field-by-field reference for a kit's spec.yaml, including credentials, network rules, environment, setup, files, agent instructions, and the sandbox block.
|
||||
keywords: sandboxes, sbx, kits, spec.yaml, reference, schema, fields
|
||||
weight: 22
|
||||
weight: 50
|
||||
---
|
||||
|
||||
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
|
||||
@@ -66,7 +66,7 @@ What changed in v2:
|
||||
Credential discovery also moved out of the kit in v2: a kit declares which
|
||||
credentials it needs and how to inject them, but where each value comes from is
|
||||
controlled by the user through
|
||||
[credential bindings](../security/credentials.md#credential-bindings).
|
||||
[credential bindings](../configuration/credentials.md#credential-bindings).
|
||||
|
||||
> [!NOTE]
|
||||
> `mixins` and `sandbox.build` are accepted by the parser, but runtime support
|
||||
@@ -217,7 +217,7 @@ file.
|
||||
A kit declares the credentials it needs and how the proxy injects them into
|
||||
outbound requests. It does not declare a host discovery source. The user
|
||||
provides the value through the secret store or the first-run prompt, and a
|
||||
[credential binding](../security/credentials.md) authorizes its use. A kit
|
||||
[credential binding](../configuration/credentials.md) authorizes its use. A kit
|
||||
can't read arbitrary host environment variables or files.
|
||||
|
||||
```yaml
|
||||
@@ -261,7 +261,7 @@ auth mechanisms.
|
||||
| Field | Description |
|
||||
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `service` | Credential identifier, matched against the value stored with `sbx secret set`. Lowercase kebab-case. |
|
||||
| `description` | Optional. Shown to the user when approving a [binding](../security/credentials.md#credential-bindings). |
|
||||
| `description` | Optional. Shown to the user when approving a [binding](../configuration/credentials.md#credential-bindings). |
|
||||
| `required` | Marks the credential as essential to the agent. If it has no binding, `sbx` warns and starts with the credential withheld. Default `false`. |
|
||||
| `provider` | Reserved for a provider registry. Accepted with a warning and no runtime effect. |
|
||||
| `apiKey` | API-key injection (see [apiKey](#apikey)). |
|
||||
|
||||
@@ -191,7 +191,7 @@ auth header before the request leaves the sandbox.
|
||||
A kit declares the service, the in-container environment variable, and how
|
||||
to inject the credential. It doesn't declare a host discovery source. The user
|
||||
provides the value through the secret store or first-run prompt, and a
|
||||
[credential binding](../security/credentials.md) authorizes its use:
|
||||
[credential binding](../configuration/credentials.md) authorizes its use:
|
||||
|
||||
```yaml
|
||||
credentials:
|
||||
@@ -215,10 +215,10 @@ request with that sentinel in `Authorization`, and the proxy overwrites
|
||||
the header with the real credential before forwarding. The real
|
||||
secret never enters the VM.
|
||||
|
||||
See [Credentials](../security/credentials.md) for how to provide the
|
||||
See [Credentials](../configuration/credentials.md) for how to provide the
|
||||
credential value on your host, other approaches for cases the example
|
||||
above doesn't fit, and what the proxy does at request time. See
|
||||
[Credential bindings](../security/credentials.md) to approve the mechanisms
|
||||
[Credential bindings](../configuration/credentials.md) to approve the mechanisms
|
||||
and domains declared by a third-party v2 kit.
|
||||
|
||||
### Inject agent memory
|
||||
@@ -370,7 +370,7 @@ For Docker Hub, include the full `docker.io` prefix. See
|
||||
> [!IMPORTANT]
|
||||
> For Docker Hub, `sbx` reuses your `sbx login` session to pull private
|
||||
> kits. For other registries, store pull credentials with
|
||||
> [`sbx secret set --registry`](../security/credentials.md#registry-credentials)
|
||||
> [`sbx secret set --registry`](../configuration/credentials.md#registry-credentials)
|
||||
> before running the sandbox:
|
||||
>
|
||||
> ```console
|
||||
@@ -498,7 +498,7 @@ For Docker Hub, include the full `docker.io` prefix — `sbx` doesn't add it
|
||||
automatically.
|
||||
|
||||
`sbx kit pull` prefers credentials stored with
|
||||
[`sbx secret set --registry`](../security/credentials.md#registry-credentials),
|
||||
[`sbx secret set --registry`](../configuration/credentials.md#registry-credentials),
|
||||
falling back to the Docker credential store. `sbx kit push` only uses the
|
||||
Docker credential store, so pushing to a private registry requires a prior
|
||||
`docker login`.
|
||||
|
||||
@@ -121,7 +121,7 @@ $ docker build -t my-org/my-template:v1 --push .
|
||||
> For Docker Hub, `sbx` reuses your `sbx login` session to pull private
|
||||
> images. For other registries (GitHub Container Registry, ECR, ACR, a
|
||||
> self-hosted Nexus, and so on), store pull credentials with
|
||||
> [`sbx secret set --registry`](../security/credentials.md#registry-credentials)
|
||||
> [`sbx secret set --registry`](../configuration/credentials.md#registry-credentials)
|
||||
> before running the sandbox:
|
||||
>
|
||||
> ```console
|
||||
@@ -186,7 +186,7 @@ interactively and want to preserve it.
|
||||
> shared with anyone you distribute it to. To keep credentials out of
|
||||
> templates, manage them with `sbx secret set` instead — the proxy injects
|
||||
> them at runtime so they're never written to the filesystem. For more
|
||||
> information, see [Manage credentials](../security/credentials.md).
|
||||
> information, see [Manage credentials](../configuration/credentials.md).
|
||||
|
||||
### Save and reuse
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: FAQ
|
||||
weight: 110
|
||||
weight: 140
|
||||
description: Frequently asked questions about Docker Sandboxes.
|
||||
keywords: docker sandboxes, sbx, faq, sign in, telemetry, clipboard, image paste, pricing, commercial use, allowlist, firewall, domains, proxy
|
||||
---
|
||||
@@ -104,7 +104,7 @@ the sandbox, to pick up the new value.
|
||||
|
||||
The sandbox itself is the safety boundary. Because agents run inside an
|
||||
isolated microVM with [network policies](governance/access-controls/network.md),
|
||||
[credential isolation](security/credentials.md), and no access to your host
|
||||
[credential isolation](security/isolation.md#credential-isolation), and no access to your host
|
||||
system outside explicitly shared paths, the usual reasons for approval prompts
|
||||
(preventing destructive commands, network access, file modifications) are
|
||||
handled by the sandbox isolation layers instead.
|
||||
@@ -151,7 +151,7 @@ inside the sandbox.
|
||||
|
||||
Shared agent skills are the exception. Run `sbx skills import` to copy skills
|
||||
from supported host directories into a persistent store shared with
|
||||
sandboxes. See [Share agent skills](workflows.md#share-agent-skills) for the
|
||||
sandboxes. See [Share agent skills](workflows/agent-skills.md) for the
|
||||
supported directories, mount behavior, and per-sandbox opt-out.
|
||||
|
||||
Keep project-specific skills and other agent configuration in the project
|
||||
@@ -211,4 +211,4 @@ storing them: install `gnome-keyring` and start `dbus-run-session`, or run the
|
||||
keyring daemon under a login session that unlocks it. Once a working Secret
|
||||
Service is available, `sbx` stores new
|
||||
secrets in the keychain again. For where each platform keeps secrets, see
|
||||
[Where secrets are stored](security/credentials.md#where-secrets-are-stored).
|
||||
[Where secrets are stored](configuration/credentials.md#where-secrets-are-stored).
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Get started with Docker Sandboxes
|
||||
linkTitle: Get started
|
||||
weight: 10
|
||||
weight: 20
|
||||
description: Configure agent credentials and work through your first Docker Sandboxes session.
|
||||
keywords: sandbox, sbx, get started, credentials, clone mode, network policy
|
||||
---
|
||||
@@ -30,7 +30,7 @@ in with OAuth. The session token stays on your host and is never stored inside
|
||||
the sandbox.
|
||||
|
||||
If you prefer to authenticate with an API key, see
|
||||
[Credentials](security/credentials.md) for how to store one with
|
||||
[Credentials](configuration/credentials.md) for how to store one with
|
||||
`sbx secret set`.
|
||||
|
||||
To give the agent access to GitHub for creating pull requests or interacting
|
||||
@@ -175,9 +175,9 @@ Then explore:
|
||||
|
||||
- [Usage guide](usage.md) — basic commands, reconnecting, workspaces, and port
|
||||
publishing.
|
||||
- [Workflow patterns](workflows.md) — Git strategies, local services, CI, and
|
||||
- [Workflow patterns](workflows/) — Git strategies, local services, CI, and
|
||||
authenticated tools.
|
||||
- [Sandbox environment files](sandbox-environments.md) — declare and share
|
||||
- [Sandbox environment files](configuration/environment-files.md) — declare and share
|
||||
repeatable local sandbox configurations with `.sbxenv.yaml`. Requires `sbx`
|
||||
0.39.0 or later.
|
||||
- [Customize with kits](customize/) — package an agent, its tools, and its
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Governance
|
||||
weight: 90
|
||||
weight: 120
|
||||
description: Control what sandboxes can access, from local developer rules to org-wide enforcement.
|
||||
keywords: docker sandboxes, governance, policy, network access, filesystem access, mcp policy, organization policy
|
||||
---
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: AI Governance Audit Logs
|
||||
linkTitle: Audit logs
|
||||
weight: 28
|
||||
weight: 30
|
||||
description: Capture, view, export, and collect structured audit records for Docker AI Governance policy decisions.
|
||||
keywords: docker sandboxes, audit log, audit logging, AI Governance, policy decision, SIEM, compliance, jsonl
|
||||
---
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Audit record reference
|
||||
linkTitle: Record reference
|
||||
weight: 40
|
||||
weight: 50
|
||||
description: Reference fields, categories, decisions, and payload types for Docker AI Governance audit records.
|
||||
keywords: docker sandboxes, audit record, audit schema, AI Governance, policy decision, action_type, jsonl
|
||||
---
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: SIEM forwarding
|
||||
linkTitle: SIEM forwarding
|
||||
weight: 35
|
||||
weight: 40
|
||||
description: Forward Docker AI Governance audit events to Splunk, Dynatrace, or Datadog.
|
||||
keywords: docker sandboxes, SIEM, audit logs, Splunk, Dynatrace, Datadog, AI Governance, forwarding, NDJSON
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Monitor and enforce
|
||||
weight: 30
|
||||
weight: 40
|
||||
description: Inspect active sandbox governance rules, collect audit records, and enforce organization sign-in.
|
||||
keywords: docker sandboxes, governance monitoring, audit logs, sign-in enforcement, policy enforcement
|
||||
---
|
||||
|
||||
@@ -141,7 +141,7 @@ The `PROXY` column shows how the request left the sandbox:
|
||||
|
||||
| Value | Description |
|
||||
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
|
||||
| `forward` | Routed through the forward proxy. Supports [credential injection](../../security/credentials.md). |
|
||||
| `forward` | Routed through the forward proxy. Supports [credential injection](../../configuration/credentials.md). |
|
||||
| `forward-bypass` | Routed through the forward proxy without credential injection. |
|
||||
| `transparent` | Intercepted by the transparent proxy. Policy is enforced but credential injection is not available. |
|
||||
| `network` | Non-HTTP traffic (raw TCP, UDP, ICMP). TCP can be allowed with a policy rule. UDP and ICMP are always blocked. |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Sign-in enforcement
|
||||
linkTitle: Sign-in enforcement
|
||||
weight: 30
|
||||
weight: 20
|
||||
description: Require Docker Sandboxes users to sign in as members of your organization, enforced through endpoint management.
|
||||
keywords: docker sandboxes, sign-in enforcement, organization enforcement, sbx login, MDM, configuration profile, registry key, allowedOrgs
|
||||
aliases:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Reference
|
||||
weight: 40
|
||||
weight: 50
|
||||
description: Reference material for Docker AI Governance policy APIs and policy syntax.
|
||||
keywords: docker sandboxes, governance reference, governance API, policy reference
|
||||
---
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Install Docker Sandboxes
|
||||
linkTitle: Install
|
||||
weight: 5
|
||||
weight: 10
|
||||
description: Install the sbx CLI on macOS, Windows, or Linux and sign in to Docker Sandboxes.
|
||||
keywords: sandbox, sbx, install, macOS, Windows, Linux, Ubuntu
|
||||
---
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Editor and app integrations
|
||||
linkTitle: Integrations
|
||||
weight: 37
|
||||
weight: 70
|
||||
description: Connect editors and desktop apps to a Docker Sandbox over SSH.
|
||||
keywords: docker sandboxes, ssh, integrations, vs code, cursor, remote development, sbx
|
||||
---
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title: MCP gateway
|
||||
description: Register MCP servers, authorize OAuth-backed servers, and connect MCP tools to Docker Sandboxes.
|
||||
keywords: docker sandboxes, sbx, MCP gateway, Model Context Protocol, MCP servers, sbx mcp, static MCP, OAuth
|
||||
weight: 50
|
||||
weight: 80
|
||||
---
|
||||
|
||||
Docker Sandboxes includes an MCP gateway for connecting agents to Model Context
|
||||
|
||||
@@ -3,7 +3,7 @@ title: Docker Sandboxes release notes
|
||||
linkTitle: Release notes
|
||||
description: New features, bug fixes, and changes in Docker Sandboxes
|
||||
keywords: docker sandboxes, sbx, release notes, changelog
|
||||
weight: 120
|
||||
weight: 150
|
||||
toc_min: 1
|
||||
toc_max: 2
|
||||
tags:
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Security model
|
||||
linkTitle: Security model
|
||||
weight: 80
|
||||
weight: 110
|
||||
description: Trust boundaries, isolation layers, and security properties of Docker Sandboxes.
|
||||
keywords: docker sandboxes, security model, isolation, trust boundaries, microVM
|
||||
---
|
||||
@@ -112,7 +112,7 @@ store is mounted read-write, so one sandbox can modify instructions or scripts
|
||||
that an agent later uses in another sandbox. This doesn't expose the rest of
|
||||
the host filesystem or create a direct network path between sandboxes, but it
|
||||
does put participating sandboxes in the same trust boundary. See
|
||||
[Share agent skills](../workflows.md#share-agent-skills) for details and the
|
||||
[Share agent skills](../workflows/agent-skills.md) for details and the
|
||||
per-sandbox opt-out.
|
||||
|
||||
Local stdio MCP servers run outside the sandbox VM. If you register a local MCP
|
||||
@@ -137,6 +137,7 @@ admins.
|
||||
workspace, and credential isolation work
|
||||
- [Default security posture](defaults/): what a fresh sandbox permits and
|
||||
blocks
|
||||
- [Credentials](credentials/): how to provide and manage API keys
|
||||
- [Manage credentials](../configuration/credentials.md): provide and manage API
|
||||
keys while keeping their values outside the sandbox
|
||||
- [Governance](../governance/): configure network, filesystem, and MCP access
|
||||
controls locally or across your organization
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Default security posture
|
||||
linkTitle: Defaults
|
||||
weight: 15
|
||||
weight: 20
|
||||
description: What a sandbox permits and blocks before you change any settings.
|
||||
keywords: docker sandboxes, security defaults, network policy, credentials, shared skills, sbx
|
||||
---
|
||||
@@ -38,7 +38,7 @@ Sandboxes for supported agents mount a persistent shared skills store
|
||||
read-write by default. Every sandbox that uses the store can change skills that
|
||||
other participating sandboxes may load. Use `--no-share-skills` when creating a
|
||||
sandbox to keep it outside this shared trust boundary. See
|
||||
[Share agent skills](../workflows.md#share-agent-skills).
|
||||
[Share agent skills](../workflows/agent-skills.md).
|
||||
|
||||
## Credential defaults
|
||||
|
||||
@@ -47,7 +47,7 @@ No credentials are available to the sandbox unless you provide them using
|
||||
host-side proxy injects them into outbound HTTP headers. The agent cannot
|
||||
read the raw credential values.
|
||||
|
||||
See [Credentials](credentials.md) for setup instructions.
|
||||
See [Credentials](../configuration/credentials.md) for setup instructions.
|
||||
|
||||
## Agent capabilities inside the sandbox
|
||||
|
||||
|
||||
@@ -22,7 +22,7 @@ processes, files, or resources outside its defined boundaries.
|
||||
are invisible to your host and to other sandboxes
|
||||
- **Filesystem isolation:** your workspace directory and, for supported agents
|
||||
that haven't opted out, the dedicated [shared skills
|
||||
store](../workflows.md#share-agent-skills) are shared with the host. The rest
|
||||
store](../workflows/agent-skills.md) are shared with the host. The rest
|
||||
of the VM filesystem persists across restarts but is removed when you delete
|
||||
the sandbox. Symlinks pointing outside the workspace scope are not followed.
|
||||
- **Full cleanup:** when you remove a sandbox with `sbx rm`, the VM and
|
||||
@@ -36,13 +36,13 @@ hypervisor boundary is the isolation control, not in-VM privilege separation.
|
||||
Each sandbox has its own isolated network. Sandboxes cannot communicate
|
||||
directly with each other or share a network with your host. To reach a service
|
||||
running on the host through a policy-controlled connection, see
|
||||
[Accessing host services from a sandbox](../workflows.md#accessing-host-services-from-a-sandbox).
|
||||
[Accessing host services from a sandbox](../workflows/development.md#accessing-host-services-from-a-sandbox).
|
||||
|
||||
All outbound TCP traffic passes through a proxy on your host that enforces the
|
||||
[network access policy](../governance/access-controls/network.md). The sandbox
|
||||
routes traffic through either a forward proxy or a transparent proxy depending
|
||||
on the client's configuration. Both enforce the network policy. Only the
|
||||
forward proxy [injects credentials](credentials.md) for AI services.
|
||||
forward proxy [injects credentials](../configuration/credentials.md) for AI services.
|
||||
|
||||
Direct external UDP and ICMP are blocked at the network layer. DNS queries use
|
||||
the sandbox's internal resolver, which enforces network policy. TCP connections
|
||||
@@ -51,7 +51,7 @@ are allowed only when a policy rule matches the destination.
|
||||
For the default set of allowed domains, see
|
||||
[Default security posture](defaults.md). To forward allowed traffic through a
|
||||
corporate or upstream proxy, see
|
||||
[Configure an upstream proxy](../upstream-proxy.md).
|
||||
[Configure an upstream proxy](../configuration/upstream-proxy.md).
|
||||
|
||||
## Docker Engine isolation
|
||||
|
||||
@@ -104,7 +104,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 workflows](../workflows.md#git-workflows) for the workflow side of
|
||||
See [Git workflows](../workflows/git.md) for the workflow side of
|
||||
each.
|
||||
|
||||
### Direct mount (default)
|
||||
@@ -159,7 +159,7 @@ or any tracked file on your host.
|
||||
> inspection**. Your repository is still mounted read-only into the sandbox,
|
||||
> including untracked files and files excluded by `.gitignore`. Files such as
|
||||
> `.env` remain readable by the agent. Store secrets outside your working
|
||||
> directory or use [credential isolation](credentials.md) instead.
|
||||
> directory or use [credential isolation](#credential-isolation) instead.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@@ -226,4 +226,4 @@ environment variables or files inside the sandbox unless you explicitly set
|
||||
them. This means a compromised sandbox cannot read API keys from the local
|
||||
environment.
|
||||
|
||||
For how to store and manage credentials, see [Credentials](credentials.md).
|
||||
For how to store and manage credentials, see [Credentials](../configuration/credentials.md).
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Troubleshooting
|
||||
weight: 100
|
||||
weight: 130
|
||||
description: Resolve common issues when using Docker Sandboxes.
|
||||
keywords: docker sandboxes, sbx, troubleshooting, diagnostics, reset, network policy, git, ssh
|
||||
---
|
||||
@@ -121,7 +121,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](workflows.md#accessing-host-services-from-a-sandbox).
|
||||
See [Accessing host services from a sandbox](workflows/development.md#accessing-host-services-from-a-sandbox).
|
||||
|
||||
## Docker authentication failure
|
||||
|
||||
@@ -136,7 +136,7 @@ If the agent can't reach its model provider or you see API key errors, the key
|
||||
is likely invalid, expired, or not configured. Verify it's set in your shell
|
||||
configuration file and that you sourced it or opened a new terminal.
|
||||
|
||||
For agents that use the [credential proxy](security/credentials.md), make sure
|
||||
For agents that use the [credential proxy](configuration/credentials.md), make sure
|
||||
you haven't set the API key to an invalid value inside the sandbox — the proxy
|
||||
injects credentials automatically on outbound requests.
|
||||
|
||||
@@ -271,7 +271,7 @@ the command again:
|
||||
## Sandbox commits aren't signed
|
||||
|
||||
Docker Sandboxes can sign Git commits with SSH keys from your host agent.
|
||||
For setup steps, see [Commit signing](workflows.md#commit-signing).
|
||||
For setup steps, see [Commit signing](workflows/git.md#commit-signing).
|
||||
|
||||
If `ssh-add -L` prints `The agent has no identities.`, the sandbox can reach
|
||||
the forwarded agent, but the host agent doesn't have a loaded key. Load the
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
title: Usage
|
||||
weight: 20
|
||||
weight: 30
|
||||
description: Basic sbx commands for creating, managing, and connecting to Docker Sandboxes.
|
||||
keywords: docker sandboxes, sbx, usage, run, create, stop, remove, ports, workspaces
|
||||
---
|
||||
|
||||
Use this page as a command-oriented guide to day-to-day `sbx` operations. For
|
||||
scenario-based recommendations, see [Workflow patterns](workflows.md).
|
||||
scenario-based recommendations, see [Workflow patterns](workflows/).
|
||||
|
||||
## Sign in
|
||||
|
||||
@@ -17,7 +17,7 @@ $ sbx login
|
||||
```
|
||||
|
||||
For scripts or CI runners where a browser isn't available, see
|
||||
[CI and headless use](workflows.md#ci-and-headless-use).
|
||||
[CI and headless use](workflows/automation.md).
|
||||
|
||||
## Start, stop, and remove
|
||||
|
||||
@@ -163,9 +163,9 @@ afterward. Restart a running agent, or stop and start the sandbox, to pick up
|
||||
the new value.
|
||||
|
||||
Environment variables are readable by processes inside the sandbox. For API
|
||||
keys and other credentials, use [`sbx secret set`](security/credentials.md#store-a-secret)
|
||||
keys and other credentials, use [`sbx secret set`](configuration/credentials.md#store-a-secret)
|
||||
for a supported service or the experimental
|
||||
[`sbx secret set-custom`](security/credentials.md#custom-secrets) for a
|
||||
[`sbx secret set-custom`](configuration/credentials.md#custom-secrets) for a
|
||||
credential sent to known hosts. The host-side proxy can then inject the real
|
||||
value without exposing it to the agent.
|
||||
|
||||
@@ -214,7 +214,7 @@ it when you create the sandbox:
|
||||
`/run/sandbox/source`, but only with read access.
|
||||
|
||||
For guidance on branch strategy, fetching work from a sandbox, and parallel
|
||||
agent workflows, see [Git workflows](workflows.md#git-workflows). For the
|
||||
agent workflows, see [Git workflows](workflows/git.md). For the
|
||||
security model behind each mode, see
|
||||
[Workspace isolation](security/isolation.md#workspace-isolation).
|
||||
|
||||
@@ -333,13 +333,13 @@ $ sbx ports my-sandbox --unpublish 8080:3000
|
||||
When `sbx run` re-attaches to an existing sandbox, it ignores `--publish`. Use
|
||||
`sbx ports` to publish ports on that sandbox. For dev server and host-service
|
||||
recipes, see
|
||||
[Local services](workflows.md#local-services).
|
||||
[Local services](workflows/development.md#local-services).
|
||||
|
||||
## What persists
|
||||
|
||||
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. Your workspace files and the
|
||||
[shared agent skills store](workflows.md#share-agent-skills) remain on your
|
||||
[shared agent skills store](workflows/agent-skills.md) remain on your
|
||||
host. To preserve a configured environment, create a [custom
|
||||
template](customize/templates.md) or use a [kit](customize/kits.md).
|
||||
@@ -1,589 +0,0 @@
|
||||
---
|
||||
title: Workflow patterns
|
||||
linkTitle: Workflows
|
||||
weight: 30
|
||||
description: Workflow patterns for Docker Sandboxes, covering shared agent skills, git strategies, local services, authenticated tools, and CI integration.
|
||||
keywords: docker sandboxes, sbx, workflows, agent skills, shared skills, 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).
|
||||
|
||||
## Share agent skills
|
||||
|
||||
Shared agent skills make skills from supported agents on your host available
|
||||
inside your sandboxes. Importing copies the skills into a persistent store that
|
||||
survives sandbox deletion and is shared by default with new sandboxes that run
|
||||
a supported agent.
|
||||
|
||||
> [!NOTE]
|
||||
> Shared agent skills are experimental.
|
||||
|
||||
Preview the skills that `sbx` finds without copying them:
|
||||
|
||||
```console
|
||||
$ sbx skills import --dry-run
|
||||
```
|
||||
|
||||
The command scans the following directories in order and copies each skill
|
||||
subdirectory into the shared store. When the sandbox starts, `sbx` mounts the
|
||||
store at the path the agent reads inside the sandbox.
|
||||
|
||||
| Agent | Host source | Sandbox mount target |
|
||||
| ----------- | ------------------- | ----------------------------- |
|
||||
| Claude Code | `~/.claude/skills` | `/home/agent/.claude/skills` |
|
||||
| Codex | `~/.agents/skills` | `/home/agent/.agents/skills` |
|
||||
| Copilot | `~/.copilot/skills` | `/home/agent/.copilot/skills` |
|
||||
| Cursor | `~/.cursor/skills` | `/home/agent/.cursor/skills` |
|
||||
| Droid | `~/.factory/skills` | `/home/agent/.factory/skills` |
|
||||
|
||||
All imported skills go into the same store, regardless of their source. If
|
||||
more than one source contains a skill with the same directory name, the skill
|
||||
from the first source in the table wins and `sbx` warns about the others.
|
||||
|
||||
Import the skills:
|
||||
|
||||
```console
|
||||
$ sbx skills import
|
||||
```
|
||||
|
||||
The final output reports the shared store path. The default locations are:
|
||||
|
||||
| Platform | Shared store path |
|
||||
| -------- | --------------------------------------------------------------------------- |
|
||||
| macOS | `~/Library/Application Support/com.docker.sandboxes/sandboxes/agent-skills` |
|
||||
| Linux | `~/.local/state/sandboxes/sandboxes/agent-skills` |
|
||||
| Windows | `%LOCALAPPDATA%\DockerSandboxes\sandboxes\state\agent-skills` |
|
||||
|
||||
On Linux, `sbx` uses `$XDG_STATE_HOME/sandboxes/sandboxes/agent-skills` when
|
||||
`XDG_STATE_HOME` is set.
|
||||
|
||||
When a skill already exists in the store, `sbx` prompts before replacing it.
|
||||
Use `--force` to replace existing skills without prompts. Importing replaces
|
||||
the complete skill directory rather than merging files. Run the import command
|
||||
again when you want to copy updates from the host. Running `sbx reset` clears
|
||||
the shared store.
|
||||
|
||||
Sandboxes created with `sbx` version 0.37.0 or later for a supported agent are
|
||||
configured to mount the store read-write by default. These sandboxes mount the
|
||||
current contents of the store each time they start, so you can import skills
|
||||
before or after creating them. To create a sandbox without the shared store,
|
||||
use `--no-share-skills`:
|
||||
|
||||
```console
|
||||
$ sbx run --no-share-skills claude
|
||||
```
|
||||
|
||||
Upgrading `sbx` does not enable shared skills for sandboxes created with an
|
||||
earlier version. Remove and recreate those sandboxes after upgrading. The
|
||||
`--no-share-skills` option also only applies when the sandbox is created. To
|
||||
turn off shared skills for an existing sandbox, remove it and recreate it with
|
||||
the option.
|
||||
|
||||
> [!WARNING]
|
||||
> The shared skills store is mounted read-write. A sandbox can modify any skill
|
||||
> in the store, and another sandbox can later load the modified instructions or
|
||||
> run the modified scripts. The store is dedicated sandbox state, so this does
|
||||
> not by itself execute the modified skill on your host. It does put every
|
||||
> sandbox that shares the store in the same trust boundary. Use
|
||||
> `--no-share-skills` to keep a sandbox outside that boundary.
|
||||
|
||||
Some agents scan for skills when a session starts. If imported skills don't
|
||||
appear in an existing session, start another agent session.
|
||||
|
||||
## Git workflows
|
||||
|
||||
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:
|
||||
|
||||
| | 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 | — |
|
||||
|
||||
### 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.
|
||||
|
||||
1. Check out the branch you want to work on:
|
||||
|
||||
```console
|
||||
$ git checkout -b feat/my-feature
|
||||
```
|
||||
|
||||
2. Start the sandbox. No special flags needed:
|
||||
|
||||
```console
|
||||
$ sbx run claude
|
||||
```
|
||||
|
||||
3. The agent edits files in your working tree. Review diffs, stage, and
|
||||
commit as you normally would:
|
||||
|
||||
```console
|
||||
$ git diff
|
||||
$ git add -p
|
||||
$ git commit
|
||||
$ 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.
|
||||
|
||||
### Clone mode
|
||||
|
||||
In clone mode, `sbx` creates a separate Git clone inside the sandbox. The agent
|
||||
edits this clone instead of your host working tree. Its changes stay inside the
|
||||
sandbox until you fetch a branch or the agent pushes one to a remote. Your host
|
||||
repository is also available at `/run/sandbox/source`, but only with read
|
||||
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.
|
||||
|
||||
> [!NOTE]
|
||||
> `--clone` is a create-time flag and cannot be changed on an existing
|
||||
> 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
|
||||
|
||||
1. Start a clone-mode sandbox:
|
||||
|
||||
```console
|
||||
$ sbx run --clone claude
|
||||
```
|
||||
|
||||
2. Ask the agent to create a branch before it starts editing:
|
||||
|
||||
> Create a branch `feat/my-feature` and make the changes.
|
||||
|
||||
3. Fetch the agent's branch when it's done:
|
||||
|
||||
```console
|
||||
$ git fetch sandbox-<name>
|
||||
$ git log sandbox-<name>/feat/my-feature
|
||||
$ git diff main..sandbox-<name>/feat/my-feature
|
||||
```
|
||||
|
||||
4. Pull the branch to the host and push, or ask the agent to push directly:
|
||||
|
||||
```console
|
||||
# Pull to host, then push
|
||||
$ git checkout -b feat/my-feature sandbox-<name>/feat/my-feature
|
||||
$ git push -u origin feat/my-feature
|
||||
$ gh pr create
|
||||
|
||||
# Or ask the agent
|
||||
# "Push feat/my-feature to origin and open a PR."
|
||||
```
|
||||
|
||||
#### Parallel tasks
|
||||
|
||||
1. Start a clone-mode sandbox and open the
|
||||
[agents view](agents/claude-code.md#agents-view):
|
||||
|
||||
```console
|
||||
$ sbx run --clone claude
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```markdown
|
||||
Always start each task on its own git branch before making changes.
|
||||
```
|
||||
|
||||
3. Fetch all branches when the agents are done:
|
||||
|
||||
```console
|
||||
$ git fetch sandbox-<name>
|
||||
$ git log sandbox-<name>/feat/task-a
|
||||
$ git log sandbox-<name>/feat/task-b
|
||||
```
|
||||
|
||||
4. Check out the branches you want to keep and open PRs as normal.
|
||||
|
||||
### Host worktree
|
||||
|
||||
You can create a Git worktree on your host and point the sandbox at it. The
|
||||
agent edits files directly in the worktree — but because the sandbox mounts
|
||||
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.
|
||||
|
||||
1. Create the worktree on the host:
|
||||
|
||||
```console
|
||||
$ git worktree add -b feat/my-feature ../my-feature-work
|
||||
```
|
||||
|
||||
2. Start the sandbox with the worktree as the workspace:
|
||||
|
||||
```console
|
||||
$ sbx run claude ../my-feature-work
|
||||
```
|
||||
|
||||
3. The agent edits files. When it's done, commit and push from the host:
|
||||
|
||||
```console
|
||||
$ cd ../my-feature-work
|
||||
$ git diff
|
||||
$ git add -p && git commit
|
||||
$ git push -u origin feat/my-feature
|
||||
$ 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 the port when you create the sandbox, or publish it
|
||||
later with `sbx ports`.
|
||||
|
||||
## 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. A port mapping of
|
||||
`8080:3000` publishes sandbox port 3000 on host port 8080.
|
||||
|
||||
If you know which ports you need, publish them when you create the sandbox:
|
||||
|
||||
```console
|
||||
$ sbx run --publish 8080:3000 --name my-sandbox claude
|
||||
```
|
||||
|
||||
For an existing sandbox, use [`sbx ports`](/reference/cli/sbx/ports/) to
|
||||
forward traffic from your host.
|
||||
|
||||
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
|
||||
$ open http://localhost:8080
|
||||
```
|
||||
|
||||
To let the OS pick a free host port instead of choosing one yourself, specify
|
||||
only the sandbox port. Then use `sbx ports` to check which host port was
|
||||
assigned:
|
||||
|
||||
```console
|
||||
$ sbx ports my-sandbox --publish 3000
|
||||
$ sbx ports my-sandbox
|
||||
```
|
||||
|
||||
`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.
|
||||
|
||||
When `sbx run` re-attaches to an existing sandbox, it ignores `--publish`. Use
|
||||
`sbx ports` to publish ports on that sandbox. 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
|
||||
sign commits with your SSH key without the private key ever leaving your
|
||||
host.
|
||||
|
||||
1. On your host, make sure the signing key is loaded in your SSH agent:
|
||||
|
||||
```console
|
||||
$ ssh-add ~/.ssh/id_ed25519
|
||||
$ ssh-add -L # confirm the key appears
|
||||
```
|
||||
|
||||
2. Inside the sandbox, configure Git to sign with SSH. Use the forwarded key
|
||||
directly rather than a file path, since host paths don't exist inside the
|
||||
sandbox:
|
||||
|
||||
```console
|
||||
$ git config --global gpg.format ssh
|
||||
$ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)"
|
||||
```
|
||||
|
||||
3. Sign commits as usual:
|
||||
|
||||
```console
|
||||
$ git commit -S -m "feat: my change"
|
||||
```
|
||||
|
||||
To apply this configuration automatically to every sandbox, use the
|
||||
[`git-ssh-sign`](https://github.com/docker/sbx-kits-contrib/tree/main/git-ssh-sign)
|
||||
community kit, which handles all of the above setup. See [Kits](customize/kits.md)
|
||||
if you want to package it alongside other sandbox customizations.
|
||||
|
||||
For troubleshooting, see
|
||||
[Sandbox commits aren't signed](troubleshooting.md#sandbox-commits-arent-signed).
|
||||
|
||||
## Authenticated CLI tools
|
||||
|
||||
The sandbox proxy handles API credentials for model providers automatically,
|
||||
but agents often also need credentials for tools like `gh`, `docker`, or a
|
||||
secrets manager. Configure the credential source on your host, and the proxy
|
||||
injects the resolved value into matching requests from the sandbox. Dynamic
|
||||
secret sources can retrieve a value from an authenticated host CLI without
|
||||
copying the value into the secret store.
|
||||
|
||||
> [!NOTE]
|
||||
> Service secrets are global by default, so all future sandboxes can use them.
|
||||
> Sandboxes that already exist when you run `sbx secret set` do not
|
||||
> receive the updated value. To update a running sandbox, scope the secret to
|
||||
> it directly: `sbx secret set <service> --sandbox <sandbox-name>`.
|
||||
|
||||
### GitHub CLI
|
||||
|
||||
Store your GitHub token as a sandbox secret. The proxy injects it into
|
||||
outbound requests, so `gh` works inside the sandbox without any additional
|
||||
configuration:
|
||||
|
||||
```console
|
||||
$ sbx secret set github --command 'gh auth token'
|
||||
```
|
||||
|
||||
The daemon runs `gh auth token` on the host and caches its output for 55 minutes
|
||||
by default. After the cache expires, it runs the command again, so token updates
|
||||
from `gh` don't need to be copied into `sbx` manually. Use `--refresh on-demand`
|
||||
to run the command for every credential use.
|
||||
|
||||
The agent can then create pull requests, open issues, comment on PRs, and
|
||||
interact with the GitHub API the same way it would from your host:
|
||||
|
||||
```console
|
||||
# Inside the sandbox
|
||||
$ gh pr create --title "feat: my feature" --body "..."
|
||||
$ gh issue list
|
||||
```
|
||||
|
||||
The token is never stored in plaintext inside the sandbox. See
|
||||
[GitHub token](security/credentials.md#github-token) for details.
|
||||
|
||||
### Docker registry
|
||||
|
||||
When using Docker Hub, authentication is handled automatically; `sbx` reuses
|
||||
your existing login session. For other registries, you need to configure
|
||||
credentials for `sbx` so it can pull private [templates](customize/templates.md)
|
||||
and kits when creating a sandbox:
|
||||
|
||||
```console
|
||||
$ gh auth token | sbx secret set --all-sandboxes --registry ghcr.io \
|
||||
--username <github-username> --password-stdin
|
||||
$ echo "$ACR_PASSWORD" | sbx secret set --all-sandboxes \
|
||||
--registry myregistry.azurecr.io \
|
||||
--username myuser --password-stdin
|
||||
```
|
||||
|
||||
Add `-g` or a sandbox name when the agent needs to run authenticated
|
||||
`docker pull` or `docker push` commands from inside the sandbox. The host-side
|
||||
proxy handles the registry login without writing the credential into the
|
||||
sandbox.
|
||||
|
||||
Images and containers built inside the sandbox run on the sandbox's private
|
||||
Docker daemon, not your host's. They're deleted when the sandbox is removed.
|
||||
|
||||
For information on how registry credentials differ from other secrets,
|
||||
per-registry username requirements, and all-sandbox versus per-sandbox scoping, see
|
||||
[Registry credentials](security/credentials.md#registry-credentials).
|
||||
|
||||
### Sourcing credentials from 1Password
|
||||
|
||||
Install the 1Password CLI, sign in on the host, and pass an `op://` reference to
|
||||
`sbx secret set`. The secret store records the reference, and the daemon uses
|
||||
`op read` on the host when the proxy needs the credential:
|
||||
|
||||
```console
|
||||
$ sbx secret set github --ref 'op://Work/GitHub/token'
|
||||
$ sbx secret set anthropic --ref 'op://Work/Anthropic/credential'
|
||||
```
|
||||
|
||||
The real value stays on your host, and the sandbox sees the proxy-managed
|
||||
placeholder. Service secrets are cached for 55 minutes by default. To retrieve
|
||||
the value from 1Password for every credential use, set the refresh policy:
|
||||
|
||||
```console
|
||||
$ sbx secret set anthropic \
|
||||
--ref 'op://Work/Anthropic/credential' \
|
||||
--refresh on-demand
|
||||
```
|
||||
|
||||
### Sourcing credentials from AWS Secrets Manager
|
||||
|
||||
Install and authenticate the AWS CLI on the host, then register the secret's
|
||||
ARN. The daemon calls AWS Secrets Manager when the proxy needs the value:
|
||||
|
||||
```console
|
||||
$ sbx secret set anthropic \
|
||||
--ref 'arn:aws:secretsmanager:us-west-2:123456789012:secret:anthropic-api-key'
|
||||
```
|
||||
|
||||
See [Use a dynamic secret source](security/credentials.md#use-a-dynamic-secret-source)
|
||||
for refresh policies, verification options, custom secrets, and provider
|
||||
account or profile selection.
|
||||
|
||||
## CI and headless use
|
||||
|
||||
For CI environments and scripts where a browser isn't available, authenticate
|
||||
with a Docker Personal Access Token (PAT):
|
||||
|
||||
```console
|
||||
$ echo "$DOCKER_PAT" | sbx login --username <your-docker-id> --password-stdin
|
||||
```
|
||||
|
||||
Generate a PAT from your
|
||||
[Docker account settings](https://app.docker.com/settings/personal-access-tokens)
|
||||
with at least **Read** scope.
|
||||
|
||||
From there, the rest of the `sbx` workflow is the same as interactive use.
|
||||
Create the sandbox in the background with `sbx create`, run agent tasks with
|
||||
`sbx exec`, and clean up with `sbx rm`:
|
||||
|
||||
```console
|
||||
$ sbx create --name ci-task --clone claude
|
||||
$ sbx run --name ci-task # attach and give instructions, or use sbx exec for one-off commands
|
||||
$ git fetch sandbox-ci-task
|
||||
$ sbx rm ci-task
|
||||
```
|
||||
|
||||
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
|
||||
variables each service reads), import them all at once:
|
||||
|
||||
```console
|
||||
$ sbx secret import --all
|
||||
```
|
||||
|
||||
To overwrite an existing stored entry, add `--force`. To pass a value from your
|
||||
CI provider's secret store, use `-t`. For example, in a GitHub Actions step:
|
||||
|
||||
```yaml
|
||||
- run: sbx secret set anthropic -t "${{ secrets.ANTHROPIC_API_KEY }}"
|
||||
```
|
||||
|
||||
## Sandbox environments
|
||||
|
||||
For a declarative alternative to `sbx run` flags, see
|
||||
[Sandbox environment files](sandbox-environments.md).
|
||||
|
||||
## 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 policies](governance/access-controls/organization.md) for
|
||||
controls that organization administrators apply across developers, such as
|
||||
network, filesystem, and MCP policies. Organization policies 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.
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Workflow patterns
|
||||
linkTitle: Workflows
|
||||
weight: 50
|
||||
description: Choose a Docker Sandboxes workflow for agent skills, Git, local development, authenticated tools, or headless automation.
|
||||
keywords: docker sandboxes, sbx, workflows, agent skills, shared skills, clone mode, git, local development, authentication, ci, headless
|
||||
toc_max: 2
|
||||
---
|
||||
|
||||
Choose a workflow based on how you want to develop, authenticate tools, or run
|
||||
sandboxes in automation. For command syntax and lifecycle basics, see
|
||||
[Usage](../usage.md).
|
||||
|
||||
## Choose how code moves
|
||||
|
||||
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)
|
||||
to choose a strategy for single or parallel tasks.
|
||||
|
||||
## Develop in the sandbox
|
||||
|
||||
Each sandbox has a private Docker daemon and runtime for building images,
|
||||
installing dependencies, and running tests. You can publish services from the
|
||||
sandbox or connect to services on the host. See
|
||||
[Develop and test locally](development.md).
|
||||
|
||||
Tools inside the sandbox can use credentials configured on the host without
|
||||
copying secret values into the VM. See
|
||||
[Authenticate command-line tools](authentication.md) for GitHub CLI, registry,
|
||||
and external secret-provider workflows.
|
||||
|
||||
## Reuse and automate workflows
|
||||
|
||||
Sandbox environment files work like Compose files for sandboxes: they capture
|
||||
project configuration in a versioned YAML file. Use `.sbxenv.yaml` to define
|
||||
the agent, workspaces, tools, resources, credentials, and ports so contributors
|
||||
can start a consistent environment without reproducing CLI flags and setup
|
||||
steps. See [Sandbox environment files](../configuration/environment-files.md).
|
||||
|
||||
You can also import skills from supported host agents into a persistent store
|
||||
shared with new sandboxes. See [Share agent skills](agent-skills.md).
|
||||
|
||||
For unattended jobs, use headless authentication and manage the sandbox
|
||||
lifecycle from scripts. See [Run sandboxes in CI](automation.md).
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: Share agent skills
|
||||
linkTitle: Agent skills
|
||||
weight: 40
|
||||
description: Import skills from supported host agents into a persistent store shared with Docker Sandboxes.
|
||||
keywords: docker sandboxes, sbx, agent skills, shared skills, claude code, codex, copilot, cursor, droid
|
||||
---
|
||||
|
||||
Shared agent skills make skills from supported agents on your host available
|
||||
inside your sandboxes. Importing copies the skills into a persistent store that
|
||||
survives sandbox deletion and is shared by default with new sandboxes that run
|
||||
a supported agent.
|
||||
|
||||
> [!NOTE]
|
||||
> Shared agent skills are experimental.
|
||||
|
||||
Preview the skills that `sbx` finds without copying them:
|
||||
|
||||
```console
|
||||
$ sbx skills import --dry-run
|
||||
```
|
||||
|
||||
The command scans the following directories in order and copies each skill
|
||||
subdirectory into the shared store. When the sandbox starts, `sbx` mounts the
|
||||
store at the path the agent reads inside the sandbox.
|
||||
|
||||
| Agent | Host source | Sandbox mount target |
|
||||
| ----------- | ------------------- | ----------------------------- |
|
||||
| Claude Code | `~/.claude/skills` | `/home/agent/.claude/skills` |
|
||||
| Codex | `~/.agents/skills` | `/home/agent/.agents/skills` |
|
||||
| Copilot | `~/.copilot/skills` | `/home/agent/.copilot/skills` |
|
||||
| Cursor | `~/.cursor/skills` | `/home/agent/.cursor/skills` |
|
||||
| Droid | `~/.factory/skills` | `/home/agent/.factory/skills` |
|
||||
|
||||
All imported skills go into the same store, regardless of their source. If
|
||||
more than one source contains a skill with the same directory name, the skill
|
||||
from the first source in the table wins and `sbx` warns about the others.
|
||||
|
||||
Import the skills:
|
||||
|
||||
```console
|
||||
$ sbx skills import
|
||||
```
|
||||
|
||||
The final output reports the shared store path. The default locations are:
|
||||
|
||||
| Platform | Shared store path |
|
||||
| -------- | --------------------------------------------------------------------------- |
|
||||
| macOS | `~/Library/Application Support/com.docker.sandboxes/sandboxes/agent-skills` |
|
||||
| Linux | `~/.local/state/sandboxes/sandboxes/agent-skills` |
|
||||
| Windows | `%LOCALAPPDATA%\DockerSandboxes\sandboxes\state\agent-skills` |
|
||||
|
||||
On Linux, `sbx` uses `$XDG_STATE_HOME/sandboxes/sandboxes/agent-skills` when
|
||||
`XDG_STATE_HOME` is set.
|
||||
|
||||
When a skill already exists in the store, `sbx` prompts before replacing it.
|
||||
Use `--force` to replace existing skills without prompts. Importing replaces
|
||||
the complete skill directory rather than merging files. Run the import command
|
||||
again when you want to copy updates from the host. Running `sbx reset` clears
|
||||
the shared store.
|
||||
|
||||
Sandboxes created with `sbx` version 0.37.0 or later for a supported agent are
|
||||
configured to mount the store read-write by default. These sandboxes mount the
|
||||
current contents of the store each time they start, so you can import skills
|
||||
before or after creating them. To create a sandbox without the shared store,
|
||||
use `--no-share-skills`:
|
||||
|
||||
```console
|
||||
$ sbx run --no-share-skills claude
|
||||
```
|
||||
|
||||
Upgrading `sbx` does not enable shared skills for sandboxes created with an
|
||||
earlier version. Remove and recreate those sandboxes after upgrading. The
|
||||
`--no-share-skills` option also only applies when the sandbox is created. To
|
||||
turn off shared skills for an existing sandbox, remove it and recreate it with
|
||||
the option.
|
||||
|
||||
> [!WARNING]
|
||||
> The shared skills store is mounted read-write. A sandbox can modify any skill
|
||||
> in the store, and another sandbox can later load the modified instructions or
|
||||
> run the modified scripts. The store is dedicated sandbox state, so this does
|
||||
> not by itself execute the modified skill on your host. It does put every
|
||||
> sandbox that shares the store in the same trust boundary. Use
|
||||
> `--no-share-skills` to keep a sandbox outside that boundary.
|
||||
|
||||
Some agents scan for skills when a session starts. If imported skills don't
|
||||
appear in an existing session, start another agent session.
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: Authenticate command-line tools
|
||||
linkTitle: Authenticate tools
|
||||
weight: 30
|
||||
description: Use authenticated command-line tools and dynamic secret sources inside Docker Sandboxes.
|
||||
keywords: docker sandboxes, sbx, authentication, github cli, registry, 1password, aws secrets manager
|
||||
---
|
||||
|
||||
The sandbox proxy handles API credentials for model providers automatically,
|
||||
but agents often also need credentials for tools like `gh`, `docker`, or a
|
||||
secrets manager. Configure the credential source on your host, and the proxy
|
||||
injects the resolved value into matching requests from the sandbox. Dynamic
|
||||
secret sources can retrieve a value from an authenticated host CLI without
|
||||
copying the value into the secret store.
|
||||
|
||||
> [!NOTE]
|
||||
> Service secrets are global by default, so all future sandboxes can use them.
|
||||
> Sandboxes that already exist when you run `sbx secret set` do not
|
||||
> receive the updated value. To update a running sandbox, scope the secret to
|
||||
> it directly: `sbx secret set <service> --sandbox <sandbox-name>`.
|
||||
|
||||
## GitHub CLI
|
||||
|
||||
Store your GitHub token as a sandbox secret. The proxy injects it into
|
||||
outbound requests, so `gh` works inside the sandbox without any additional
|
||||
configuration:
|
||||
|
||||
```console
|
||||
$ sbx secret set github --command 'gh auth token'
|
||||
```
|
||||
|
||||
The daemon runs `gh auth token` on the host and caches its output for 55 minutes
|
||||
by default. After the cache expires, it runs the command again, so token updates
|
||||
from `gh` don't need to be copied into `sbx` manually. Use `--refresh on-demand`
|
||||
to run the command for every credential use.
|
||||
|
||||
The agent can then create pull requests, open issues, comment on PRs, and
|
||||
interact with the GitHub API the same way it would from your host:
|
||||
|
||||
```console
|
||||
# Inside the sandbox
|
||||
$ gh pr create --title "feat: my feature" --body "..."
|
||||
$ gh issue list
|
||||
```
|
||||
|
||||
The token is never stored in plaintext inside the sandbox. See
|
||||
[GitHub token](../configuration/credentials.md#github-token) for details.
|
||||
|
||||
## Docker registry
|
||||
|
||||
When using Docker Hub, authentication is handled automatically; `sbx` reuses
|
||||
your existing login session. For other registries, you need to configure
|
||||
credentials for `sbx` so it can pull private [templates](../customize/templates.md)
|
||||
and kits when creating a sandbox:
|
||||
|
||||
```console
|
||||
$ gh auth token | sbx secret set --all-sandboxes --registry ghcr.io \
|
||||
--username <github-username> --password-stdin
|
||||
$ echo "$ACR_PASSWORD" | sbx secret set --all-sandboxes \
|
||||
--registry myregistry.azurecr.io \
|
||||
--username myuser --password-stdin
|
||||
```
|
||||
|
||||
Add `-g` or a sandbox name when the agent needs to run authenticated
|
||||
`docker pull` or `docker push` commands from inside the sandbox. The host-side
|
||||
proxy handles the registry login without writing the credential into the
|
||||
sandbox.
|
||||
|
||||
Images and containers built inside the sandbox run on the sandbox's private
|
||||
Docker daemon, not your host's. They're deleted when the sandbox is removed.
|
||||
|
||||
For information on how registry credentials differ from other secrets,
|
||||
per-registry username requirements, and all-sandbox versus per-sandbox scoping, see
|
||||
[Registry credentials](../configuration/credentials.md#registry-credentials).
|
||||
|
||||
## Source credentials from 1Password
|
||||
|
||||
Install the 1Password CLI, sign in on the host, and pass an `op://` reference to
|
||||
`sbx secret set`. The secret store records the reference, and the daemon uses
|
||||
`op read` on the host when the proxy needs the credential:
|
||||
|
||||
```console
|
||||
$ sbx secret set github --ref 'op://Work/GitHub/token'
|
||||
$ sbx secret set anthropic --ref 'op://Work/Anthropic/credential'
|
||||
```
|
||||
|
||||
The real value stays on your host, and the sandbox sees the proxy-managed
|
||||
placeholder. Service secrets are cached for 55 minutes by default. To retrieve
|
||||
the value from 1Password for every credential use, set the refresh policy:
|
||||
|
||||
```console
|
||||
$ sbx secret set anthropic \
|
||||
--ref 'op://Work/Anthropic/credential' \
|
||||
--refresh on-demand
|
||||
```
|
||||
|
||||
## Source credentials from AWS Secrets Manager
|
||||
|
||||
Install and authenticate the AWS CLI on the host, then register the secret's
|
||||
ARN. The daemon calls AWS Secrets Manager when the proxy needs the value:
|
||||
|
||||
```console
|
||||
$ sbx secret set anthropic \
|
||||
--ref 'arn:aws:secretsmanager:us-west-2:123456789012:secret:anthropic-api-key'
|
||||
```
|
||||
|
||||
See [Use a dynamic secret source](../configuration/credentials.md#use-a-dynamic-secret-source)
|
||||
for refresh policies, verification options, custom secrets, and provider
|
||||
account or profile selection.
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Run sandboxes in CI
|
||||
linkTitle: CI and headless
|
||||
weight: 50
|
||||
description: Authenticate and run Docker Sandboxes in CI systems and other headless environments.
|
||||
keywords: docker sandboxes, sbx, ci, headless, automation, personal access token
|
||||
---
|
||||
|
||||
For CI environments and scripts where a browser isn't available, authenticate
|
||||
with a Docker Personal Access Token (PAT):
|
||||
|
||||
```console
|
||||
$ echo "$DOCKER_PAT" | sbx login --username <your-docker-id> --password-stdin
|
||||
```
|
||||
|
||||
Generate a PAT from your
|
||||
[Docker account settings](https://app.docker.com/settings/personal-access-tokens)
|
||||
with at least **Read** scope.
|
||||
|
||||
From there, the rest of the `sbx` workflow is the same as interactive use.
|
||||
Create the sandbox in the background with `sbx create`, run agent tasks with
|
||||
`sbx exec`, and clean up with `sbx rm`:
|
||||
|
||||
```console
|
||||
$ sbx create --name ci-task --clone claude
|
||||
$ sbx run --name ci-task # attach and give instructions, or use sbx exec for one-off commands
|
||||
$ git fetch sandbox-ci-task
|
||||
$ sbx rm ci-task
|
||||
```
|
||||
|
||||
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](../configuration/credentials.md#built-in-services) for which
|
||||
variables each service reads), import them all at once:
|
||||
|
||||
```console
|
||||
$ sbx secret import --all
|
||||
```
|
||||
|
||||
To overwrite an existing stored entry, add `--force`. To pass a value from your
|
||||
CI provider's secret store, use `-t`. For example, in a GitHub Actions step:
|
||||
|
||||
```yaml
|
||||
- run: sbx secret set anthropic -t "${{ secrets.ANTHROPIC_API_KEY }}"
|
||||
```
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
title: Develop and test locally
|
||||
linkTitle: Local development
|
||||
weight: 20
|
||||
description: Build, test, and connect to development services in Docker Sandboxes.
|
||||
keywords: docker sandboxes, sbx, local development, build, test, ports, host services
|
||||
---
|
||||
|
||||
Use a sandbox's private runtime to build images, run tests, and connect local
|
||||
tools to development services across the sandbox boundary.
|
||||
|
||||
## 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 the port when you create the sandbox, or publish it
|
||||
later with `sbx ports`.
|
||||
|
||||
## 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. A port mapping of
|
||||
`8080:3000` publishes sandbox port 3000 on host port 8080.
|
||||
|
||||
If you know which ports you need, publish them when you create the sandbox:
|
||||
|
||||
```console
|
||||
$ sbx run --publish 8080:3000 --name my-sandbox claude
|
||||
```
|
||||
|
||||
For an existing sandbox, use [`sbx ports`](/reference/cli/sbx/ports/) to
|
||||
forward traffic from your host.
|
||||
|
||||
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
|
||||
$ open http://localhost:8080
|
||||
```
|
||||
|
||||
To let the OS pick a free host port instead of choosing one yourself, specify
|
||||
only the sandbox port. Then use `sbx ports` to check which host port was
|
||||
assigned:
|
||||
|
||||
```console
|
||||
$ sbx ports my-sandbox --publish 3000
|
||||
$ sbx ports my-sandbox
|
||||
```
|
||||
|
||||
`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.
|
||||
|
||||
When `sbx run` re-attaches to an existing sandbox, it ignores `--publish`. Use
|
||||
`sbx ports` to publish ports on that sandbox. 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
|
||||
```
|
||||
@@ -0,0 +1,218 @@
|
||||
---
|
||||
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.
|
||||
keywords: docker sandboxes, sbx, git, clone mode, direct mode, worktrees, branches, commit signing
|
||||
---
|
||||
|
||||
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:
|
||||
|
||||
| | 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 | — |
|
||||
|
||||
## 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.
|
||||
|
||||
1. Check out the branch you want to work on:
|
||||
|
||||
```console
|
||||
$ git checkout -b feat/my-feature
|
||||
```
|
||||
|
||||
2. Start the sandbox. No special flags needed:
|
||||
|
||||
```console
|
||||
$ sbx run claude
|
||||
```
|
||||
|
||||
3. The agent edits files in your working tree. Review diffs, stage, and
|
||||
commit as you normally would:
|
||||
|
||||
```console
|
||||
$ git diff
|
||||
$ git add -p
|
||||
$ git commit
|
||||
$ 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.
|
||||
|
||||
## Clone mode
|
||||
|
||||
In clone mode, `sbx` creates a separate Git clone inside the sandbox. The agent
|
||||
edits this clone instead of your host working tree. Its changes stay inside the
|
||||
sandbox until you fetch a branch or the agent pushes one to a remote. Your host
|
||||
repository is also available at `/run/sandbox/source`, but only with read
|
||||
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.
|
||||
|
||||
> [!NOTE]
|
||||
> `--clone` is a create-time flag and cannot be changed on an existing
|
||||
> 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
|
||||
|
||||
1. Start a clone-mode sandbox:
|
||||
|
||||
```console
|
||||
$ sbx run --clone claude
|
||||
```
|
||||
|
||||
2. Ask the agent to create a branch before it starts editing:
|
||||
|
||||
> Create a branch `feat/my-feature` and make the changes.
|
||||
|
||||
3. Fetch the agent's branch when it's done:
|
||||
|
||||
```console
|
||||
$ git fetch sandbox-<name>
|
||||
$ git log sandbox-<name>/feat/my-feature
|
||||
$ git diff main..sandbox-<name>/feat/my-feature
|
||||
```
|
||||
|
||||
4. Pull the branch to the host and push, or ask the agent to push directly:
|
||||
|
||||
```console
|
||||
# Pull to host, then push
|
||||
$ git checkout -b feat/my-feature sandbox-<name>/feat/my-feature
|
||||
$ git push -u origin feat/my-feature
|
||||
$ gh pr create
|
||||
|
||||
# Or ask the agent
|
||||
# "Push feat/my-feature to origin and open a PR."
|
||||
```
|
||||
|
||||
### Parallel tasks
|
||||
|
||||
1. Start a clone-mode sandbox and open the
|
||||
[agents view](../agents/claude-code.md#agents-view):
|
||||
|
||||
```console
|
||||
$ sbx run --clone claude
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```markdown
|
||||
Always start each task on its own git branch before making changes.
|
||||
```
|
||||
|
||||
3. Fetch all branches when the agents are done:
|
||||
|
||||
```console
|
||||
$ git fetch sandbox-<name>
|
||||
$ git log sandbox-<name>/feat/task-a
|
||||
$ git log sandbox-<name>/feat/task-b
|
||||
```
|
||||
|
||||
4. Check out the branches you want to keep and open PRs as normal.
|
||||
|
||||
## Host worktree
|
||||
|
||||
You can create a Git worktree on your host and point the sandbox at it. The
|
||||
agent edits files directly in the worktree — but because the sandbox mounts
|
||||
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.
|
||||
|
||||
1. Create the worktree on the host:
|
||||
|
||||
```console
|
||||
$ git worktree add -b feat/my-feature ../my-feature-work
|
||||
```
|
||||
|
||||
2. Start the sandbox with the worktree as the workspace:
|
||||
|
||||
```console
|
||||
$ sbx run claude ../my-feature-work
|
||||
```
|
||||
|
||||
3. The agent edits files. When it's done, commit and push from the host:
|
||||
|
||||
```console
|
||||
$ cd ../my-feature-work
|
||||
$ git diff
|
||||
$ git add -p && git commit
|
||||
$ git push -u origin feat/my-feature
|
||||
$ gh pr create
|
||||
```
|
||||
|
||||
## Commit signing
|
||||
|
||||
Sandboxes forward your host SSH agent into the sandbox, so the agent can
|
||||
sign commits with your SSH key without the private key ever leaving your
|
||||
host.
|
||||
|
||||
1. On your host, make sure the signing key is loaded in your SSH agent:
|
||||
|
||||
```console
|
||||
$ ssh-add ~/.ssh/id_ed25519
|
||||
$ ssh-add -L # confirm the key appears
|
||||
```
|
||||
|
||||
2. Inside the sandbox, configure Git to sign with SSH. Use the forwarded key
|
||||
directly rather than a file path, since host paths don't exist inside the
|
||||
sandbox:
|
||||
|
||||
```console
|
||||
$ git config --global gpg.format ssh
|
||||
$ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)"
|
||||
```
|
||||
|
||||
3. Sign commits as usual:
|
||||
|
||||
```console
|
||||
$ git commit -S -m "feat: my change"
|
||||
```
|
||||
|
||||
To apply this configuration automatically to every sandbox, use the
|
||||
[`git-ssh-sign`](https://github.com/docker/sbx-kits-contrib/tree/main/git-ssh-sign)
|
||||
community kit, which handles all of the above setup. See [Kits](../customize/kits.md)
|
||||
if you want to package it alongside other sandbox customizations.
|
||||
|
||||
For troubleshooting, see
|
||||
[Sandbox commits aren't signed](../troubleshooting.md#sandbox-commits-arent-signed).
|
||||
+1
-1
@@ -60,7 +60,7 @@
|
||||
"product": "Docker Sandboxes",
|
||||
"title": "Share agent skills across sandboxes",
|
||||
"description": "Import skills from supported host agents into a persistent store that sandboxes can share.",
|
||||
"url": "/ai/sandboxes/workflows/#share-agent-skills",
|
||||
"url": "/ai/sandboxes/workflows/agent-skills/",
|
||||
"published": "2026-07-24",
|
||||
"source_prs": [25588],
|
||||
"featured": false
|
||||
|
||||
Reference in new issue
Block a user