diff --git a/content/guides/claude-code-sandbox-model-runner.md b/content/guides/claude-code-sandbox-model-runner.md index 64bf063e6ff0..88e6d56c1bf7 100644 --- a/content/guides/claude-code-sandbox-model-runner.md +++ b/content/guides/claude-code-sandbox-model-runner.md @@ -88,7 +88,7 @@ $ sbx policy allow network localhost:12434 ``` For background on host access from sandboxes, see -[Accessing host services from a sandbox](../manuals/ai/sandboxes/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). diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index 075294c7ccbd..a6ec29d0d2c6 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/content/manuals/ai/sandboxes/_index.md @@ -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 diff --git a/content/manuals/ai/sandboxes/agents/_index.md b/content/manuals/ai/sandboxes/agents/_index.md index 56c6627a2ca5..d50303b3f5e3 100644 --- a/content/manuals/ai/sandboxes/agents/_index.md +++ b/content/manuals/ai/sandboxes/agents/_index.md @@ -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? diff --git a/content/manuals/ai/sandboxes/agents/claude-code.md b/content/manuals/ai/sandboxes/agents/claude-code.md index 0ea002d4e5d3..89cfc814da6e 100644 --- a/content/manuals/ai/sandboxes/agents/claude-code.md +++ b/content/manuals/ai/sandboxes/agents/claude-code.md @@ -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- $ git diff main..sandbox-/ ``` -See [Git workflows](../workflows.md#git-workflows) for clone-mode details. +See [Git workflows](../workflows/git.md) for clone-mode details. ## Base image diff --git a/content/manuals/ai/sandboxes/agents/codex.md b/content/manuals/ai/sandboxes/agents/codex.md index de8d90204f6c..fa72cf19fdcf 100644 --- a/content/manuals/ai/sandboxes/agents/codex.md +++ b/content/manuals/ai/sandboxes/agents/codex.md @@ -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 diff --git a/content/manuals/ai/sandboxes/agents/copilot.md b/content/manuals/ai/sandboxes/agents/copilot.md index 7bc20a81e177..feb5b68b92b9 100644 --- a/content/manuals/ai/sandboxes/agents/copilot.md +++ b/content/manuals/ai/sandboxes/agents/copilot.md @@ -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' diff --git a/content/manuals/ai/sandboxes/agents/cursor.md b/content/manuals/ai/sandboxes/agents/cursor.md index 6d02599e6185..0f4c3378c1f3 100644 --- a/content/manuals/ai/sandboxes/agents/cursor.md +++ b/content/manuals/ai/sandboxes/agents/cursor.md @@ -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 diff --git a/content/manuals/ai/sandboxes/agents/docker-agent.md b/content/manuals/ai/sandboxes/agents/docker-agent.md index 17eda8c947e6..0839f7cb1477 100644 --- a/content/manuals/ai/sandboxes/agents/docker-agent.md +++ b/content/manuals/ai/sandboxes/agents/docker-agent.md @@ -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 diff --git a/content/manuals/ai/sandboxes/agents/droid.md b/content/manuals/ai/sandboxes/agents/droid.md index 17fdfd30c3e8..40bfaddb74c9 100644 --- a/content/manuals/ai/sandboxes/agents/droid.md +++ b/content/manuals/ai/sandboxes/agents/droid.md @@ -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 diff --git a/content/manuals/ai/sandboxes/agents/gemini.md b/content/manuals/ai/sandboxes/agents/gemini.md index 98cb1813ce09..156fd75de2c9 100644 --- a/content/manuals/ai/sandboxes/agents/gemini.md +++ b/content/manuals/ai/sandboxes/agents/gemini.md @@ -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 diff --git a/content/manuals/ai/sandboxes/agents/kiro.md b/content/manuals/ai/sandboxes/agents/kiro.md index 62a416b720d2..b9d7bc6940ab 100644 --- a/content/manuals/ai/sandboxes/agents/kiro.md +++ b/content/manuals/ai/sandboxes/agents/kiro.md @@ -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. diff --git a/content/manuals/ai/sandboxes/agents/opencode.md b/content/manuals/ai/sandboxes/agents/opencode.md index 6d3c0b894e4d..fa192b3ca82e 100644 --- a/content/manuals/ai/sandboxes/agents/opencode.md +++ b/content/manuals/ai/sandboxes/agents/opencode.md @@ -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: diff --git a/content/manuals/ai/sandboxes/agents/shell.md b/content/manuals/ai/sandboxes/agents/shell.md index 928bfdfa8b57..70c0ac8b63c0 100644 --- a/content/manuals/ai/sandboxes/agents/shell.md +++ b/content/manuals/ai/sandboxes/agents/shell.md @@ -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: diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index ce34ce5f1246..88c8da4bdebe 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -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 diff --git a/content/manuals/ai/sandboxes/configuration/_index.md b/content/manuals/ai/sandboxes/configuration/_index.md new file mode 100644 index 000000000000..31d09f14b143 --- /dev/null +++ b/content/manuals/ai/sandboxes/configuration/_index.md @@ -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. diff --git a/content/manuals/ai/sandboxes/security/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md similarity index 98% rename from content/manuals/ai/sandboxes/security/credentials.md rename to content/manuals/ai/sandboxes/configuration/credentials.md index b0b73f70696c..9c28102d19aa 100644 --- a/content/manuals/ai/sandboxes/security/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -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 diff --git a/content/manuals/ai/sandboxes/sandbox-environments.md b/content/manuals/ai/sandboxes/configuration/environment-files.md similarity index 97% rename from content/manuals/ai/sandboxes/sandbox-environments.md rename to content/manuals/ai/sandboxes/configuration/environment-files.md index ef49db0ebf2f..7f3f53db3590 100644 --- a/content/manuals/ai/sandboxes/sandbox-environments.md +++ b/content/manuals/ai/sandboxes/configuration/environment-files.md @@ -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 | diff --git a/content/manuals/ai/sandboxes/gpu-passthrough.md b/content/manuals/ai/sandboxes/configuration/gpu-passthrough.md similarity index 98% rename from content/manuals/ai/sandboxes/gpu-passthrough.md rename to content/manuals/ai/sandboxes/configuration/gpu-passthrough.md index f4391d2b73aa..77a6a3fde64f 100644 --- a/content/manuals/ai/sandboxes/gpu-passthrough.md +++ b/content/manuals/ai/sandboxes/configuration/gpu-passthrough.md @@ -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] diff --git a/content/manuals/ai/sandboxes/upstream-proxy.md b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md similarity index 95% rename from content/manuals/ai/sandboxes/upstream-proxy.md rename to content/manuals/ai/sandboxes/configuration/upstream-proxy.md index 68b5e1ba0644..bb87cd3176b6 100644 --- a/content/manuals/ai/sandboxes/upstream-proxy.md +++ b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md @@ -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 diff --git a/content/manuals/ai/sandboxes/customize/_index.md b/content/manuals/ai/sandboxes/customize/_index.md index 0656152a770c..94e3434250a2 100644 --- a/content/manuals/ai/sandboxes/customize/_index.md +++ b/content/manuals/ai/sandboxes/customize/_index.md @@ -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: diff --git a/content/manuals/ai/sandboxes/customize/kit-examples.md b/content/manuals/ai/sandboxes/customize/kit-examples.md index ee4a19fcbd17..90c6504c0e57 100644 --- a/content/manuals/ai/sandboxes/customize/kit-examples.md +++ b/content/manuals/ai/sandboxes/customize/kit-examples.md @@ -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. diff --git a/content/manuals/ai/sandboxes/customize/kit-reference.md b/content/manuals/ai/sandboxes/customize/kit-reference.md index c48ff53b7fba..004559db8b84 100644 --- a/content/manuals/ai/sandboxes/customize/kit-reference.md +++ b/content/manuals/ai/sandboxes/customize/kit-reference.md @@ -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)). | diff --git a/content/manuals/ai/sandboxes/customize/kits.md b/content/manuals/ai/sandboxes/customize/kits.md index b47c4c1ab1fe..92e5bef2bf87 100644 --- a/content/manuals/ai/sandboxes/customize/kits.md +++ b/content/manuals/ai/sandboxes/customize/kits.md @@ -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`. diff --git a/content/manuals/ai/sandboxes/customize/templates.md b/content/manuals/ai/sandboxes/customize/templates.md index 5e5f1f21e53f..72bcade5d944 100644 --- a/content/manuals/ai/sandboxes/customize/templates.md +++ b/content/manuals/ai/sandboxes/customize/templates.md @@ -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 diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 17e63594b941..b02ddfb783a0 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -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). diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 634ab78283ea..81aa8685b477 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -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 diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index 8a6b2bc1bb06..4db45c542720 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -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 --- diff --git a/content/manuals/ai/sandboxes/governance/audit/_index.md b/content/manuals/ai/sandboxes/governance/audit/_index.md index 220cabdbda4c..35ac8c59b7da 100644 --- a/content/manuals/ai/sandboxes/governance/audit/_index.md +++ b/content/manuals/ai/sandboxes/governance/audit/_index.md @@ -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 --- diff --git a/content/manuals/ai/sandboxes/governance/audit/record-reference.md b/content/manuals/ai/sandboxes/governance/audit/record-reference.md index 1d2db0633262..6f895e72d541 100644 --- a/content/manuals/ai/sandboxes/governance/audit/record-reference.md +++ b/content/manuals/ai/sandboxes/governance/audit/record-reference.md @@ -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 --- diff --git a/content/manuals/ai/sandboxes/governance/audit/siem.md b/content/manuals/ai/sandboxes/governance/audit/siem.md index d9cca58004b5..a5511fbdef47 100644 --- a/content/manuals/ai/sandboxes/governance/audit/siem.md +++ b/content/manuals/ai/sandboxes/governance/audit/siem.md @@ -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 --- diff --git a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md index eaf065b22a7a..0ff58d417a22 100644 --- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md @@ -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 --- diff --git a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md index 9030d7e39ee2..8f2333ce8b53 100644 --- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md @@ -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. | diff --git a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md index 4a964dc3d26e..ba30413d3453 100644 --- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md @@ -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: diff --git a/content/manuals/ai/sandboxes/governance/reference/_index.md b/content/manuals/ai/sandboxes/governance/reference/_index.md index 819feab16011..5358776a0a49 100644 --- a/content/manuals/ai/sandboxes/governance/reference/_index.md +++ b/content/manuals/ai/sandboxes/governance/reference/_index.md @@ -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 --- diff --git a/content/manuals/ai/sandboxes/install.md b/content/manuals/ai/sandboxes/install.md index 845ce0cad2ff..01aa69e2d647 100644 --- a/content/manuals/ai/sandboxes/install.md +++ b/content/manuals/ai/sandboxes/install.md @@ -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 --- diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md index decfc649dcf6..f83db01d2ad1 100644 --- a/content/manuals/ai/sandboxes/integrations/_index.md +++ b/content/manuals/ai/sandboxes/integrations/_index.md @@ -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 --- diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md index 9ed3beb01b40..81ef547e8e6c 100644 --- a/content/manuals/ai/sandboxes/mcp-gateway.md +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -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 diff --git a/content/manuals/ai/sandboxes/release-notes.md b/content/manuals/ai/sandboxes/release-notes.md index a9452a085b57..04d356e2039c 100644 --- a/content/manuals/ai/sandboxes/release-notes.md +++ b/content/manuals/ai/sandboxes/release-notes.md @@ -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: diff --git a/content/manuals/ai/sandboxes/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md index 3b085fadc779..5af246133cf2 100644 --- a/content/manuals/ai/sandboxes/security/_index.md +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -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 diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index 98ef11dfad0c..95cd06402174 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -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 diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index d1aab39eae4d..913143633404 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -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). diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 349a275430a3..fc518e40ebfe 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.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 diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index dbf1ff304faa..79c37ea7a4b7 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -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). diff --git a/content/manuals/ai/sandboxes/workflows.md b/content/manuals/ai/sandboxes/workflows.md deleted file mode 100644 index b9fae5ba4537..000000000000 --- a/content/manuals/ai/sandboxes/workflows.md +++ /dev/null @@ -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-` fails until the - sandbox starts again. -- Restarting the sandbox assigns another ephemeral port to the daemon. The CLI - updates the `sandbox-` remote URL in your host repository's Git config, - so fetching continues without manual reconfiguration. -- `sbx rm` removes the sandbox, the daemon, the published port, and the - `sandbox-` remote entry from your host repository. - -#### Single task - -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- - $ git log sandbox-/feat/my-feature - $ git diff main..sandbox-/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-/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- - $ git log sandbox-/feat/task-a - $ git log sandbox-/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:/` 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 --sandbox `. - -### 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 --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 --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. diff --git a/content/manuals/ai/sandboxes/workflows/_index.md b/content/manuals/ai/sandboxes/workflows/_index.md new file mode 100644 index 000000000000..f0b24191ab10 --- /dev/null +++ b/content/manuals/ai/sandboxes/workflows/_index.md @@ -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). diff --git a/content/manuals/ai/sandboxes/workflows/agent-skills.md b/content/manuals/ai/sandboxes/workflows/agent-skills.md new file mode 100644 index 000000000000..8efaf6069e12 --- /dev/null +++ b/content/manuals/ai/sandboxes/workflows/agent-skills.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. diff --git a/content/manuals/ai/sandboxes/workflows/authentication.md b/content/manuals/ai/sandboxes/workflows/authentication.md new file mode 100644 index 000000000000..0edd3012888f --- /dev/null +++ b/content/manuals/ai/sandboxes/workflows/authentication.md @@ -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 --sandbox `. + +## 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 --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. diff --git a/content/manuals/ai/sandboxes/workflows/automation.md b/content/manuals/ai/sandboxes/workflows/automation.md new file mode 100644 index 000000000000..f7b6d38fdfe8 --- /dev/null +++ b/content/manuals/ai/sandboxes/workflows/automation.md @@ -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 --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 }}" +``` diff --git a/content/manuals/ai/sandboxes/workflows/development.md b/content/manuals/ai/sandboxes/workflows/development.md new file mode 100644 index 000000000000..3080053c0630 --- /dev/null +++ b/content/manuals/ai/sandboxes/workflows/development.md @@ -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:/` 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 +``` diff --git a/content/manuals/ai/sandboxes/workflows/git.md b/content/manuals/ai/sandboxes/workflows/git.md new file mode 100644 index 000000000000..07ccf097acd3 --- /dev/null +++ b/content/manuals/ai/sandboxes/workflows/git.md @@ -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-` fails until the + sandbox starts again. +- Restarting the sandbox assigns another ephemeral port to the daemon. The CLI + updates the `sandbox-` remote URL in your host repository's Git config, + so fetching continues without manual reconfiguration. +- `sbx rm` removes the sandbox, the daemon, the published port, and the + `sandbox-` remote entry from your host repository. + +### Single task + +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- + $ git log sandbox-/feat/my-feature + $ git diff main..sandbox-/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-/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- + $ git log sandbox-/feat/task-a + $ git log sandbox-/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). diff --git a/data/whats-new.json b/data/whats-new.json index 0277ac5b85c3..a902a240e321 100644 --- a/data/whats-new.json +++ b/data/whats-new.json @@ -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