diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index a1e71e343d..35196ee802 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -237,6 +237,7 @@ Turtlesim typesafe Ubuntu ufw +uv umask uncaptured Uncaptured @@ -259,6 +260,9 @@ windowsfilter WireMock workdir WORKDIR +[Ww]orktrees? +[Pp]assthrough +[Pp]reconfigured Xdebug xUnit XQuartz diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index bf7b77dd73..8b7876b0da 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/content/manuals/ai/sandboxes/_index.md @@ -5,11 +5,66 @@ weight: 20 params: sidebar: group: AI + badge: + color: violet + text: Experimental --- -Docker Sandboxes let you run AI coding agents in isolated environments using -the `docker sandbox` command. Sandboxes require Docker Desktop and run agents -in microVMs with private Docker daemons. +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} -For setup instructions and usage details, see the -[Docker Desktop sandboxes](docker-desktop.md) page. +Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each +sandbox gets its own Docker daemon, filesystem, and network — the agent can +build containers, install packages, and modify files without touching your host +system. + +## Get started + +Install the `sbx` CLI and sign in: + +{{< tabs >}} +{{< tab name="macOS" >}} + +```console +$ brew install docker/tap/sbx +$ sbx login +``` + +{{< /tab >}} +{{< tab name="Windows" >}} + +```powershell +> winget install -h Docker.sbx +> sbx login +``` + +{{< /tab >}} +{{< /tabs >}} + +Then launch an agent in a sandbox: + +```console +$ cd ~/my-project +$ sbx run claude +``` + +See the [get started guide](get-started.md) for a full walkthrough, or jump to +the [usage guide](usage.md) for common patterns. + +## Learn more + +- [Agents](agents/) — supported agents and per-agent configuration +- [Custom environments](agents/custom-environments.md) — build reusable sandbox + images with pre-installed tools +- [Architecture](architecture.md) — microVM isolation, workspace mounting, + networking +- [Security](security/) — isolation model, credential handling, network + policies, workspace trust +- [CLI reference](/reference/cli/sbx/) — full list of `sbx` commands and options +- [Troubleshooting](troubleshooting.md) — common issues and fixes +- [FAQ](faq.md) — login requirements, telemetry, etc + +## Docker Desktop integration + +Docker Desktop also includes a [built-in sandbox command](docker-desktop.md) +(`docker sandbox`) with a subset of features. The `sbx` CLI is recommended for +most use cases. diff --git a/content/manuals/ai/sandboxes/agents/_index.md b/content/manuals/ai/sandboxes/agents/_index.md new file mode 100644 index 0000000000..de3428d47c --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/_index.md @@ -0,0 +1,21 @@ +--- +title: Supported agents +linkTitle: Agents +weight: 30 +description: AI coding agents supported by Docker Sandboxes. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +Docker Sandboxes runs the following agents out of the box: + +- [Claude Code](claude-code/) +- [Codex](codex/) +- [Copilot](copilot/) +- [Gemini](gemini/) +- [Kiro](kiro/) +- [OpenCode](opencode/) +- [Docker Agent](docker-agent/) + +Want to pre-install tools or customize an agent's environment? +See [Custom environments](custom-environments/). diff --git a/content/manuals/ai/sandboxes/agents/claude-code.md b/content/manuals/ai/sandboxes/agents/claude-code.md new file mode 100644 index 0000000000..f606a2ee7e --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/claude-code.md @@ -0,0 +1,72 @@ +--- +title: Claude Code +weight: 10 +description: | + Use Claude Code in Docker Sandboxes with authentication, configuration, and + YOLO mode for AI-assisted development. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +Official documentation: [Claude Code](https://code.claude.com/docs) + +## Quick start + +Launch Claude Code in a sandbox by pointing it at a project directory: + +```console +$ sbx run claude ~/my-project +``` + +The workspace parameter defaults to the current directory, so `sbx run claude` +from inside your project works too. To start Claude with a specific prompt: + +```console +$ sbx run claude --name my-sandbox -- "Add error handling to the login function" +``` + +Everything after `--` is passed directly to Claude Code. You can also pipe in a +prompt from a file with `-- "$(cat prompt.txt)"`. + +## Authentication + +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): + +```console +$ sbx secret set -g anthropic +``` + +Alternatively, export the `ANTHROPIC_API_KEY` environment variable in your +shell before running the sandbox. See +[Credentials](../security/credentials.md) for details on both methods. + +**Claude subscription**: If no API key is set, Claude Code prompts you to +authenticate interactively using OAuth. The proxy handles the OAuth flow, so +credentials aren't stored inside the sandbox. + +## Configuration + +Sandboxes don't pick up user-level configuration from your host, such as +`~/.claude`. Only project-level configuration in the working directory is +available inside the sandbox. See +[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) +for workarounds. + +Any Claude Code CLI options can be passed after the `--` separator: + +```console +$ sbx run claude --name my-sandbox -- --continue +``` + +See the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference) +for available options. + +## Base image + +The sandbox uses `docker/sandbox-templates:claude-code` and launches Claude Code +with `--dangerously-skip-permissions` by default. See +[Custom environments](custom-environments.md) to build your own image on +top of this base. diff --git a/content/manuals/ai/sandboxes/agents/codex.md b/content/manuals/ai/sandboxes/agents/codex.md new file mode 100644 index 0000000000..d949ba0e15 --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/codex.md @@ -0,0 +1,66 @@ +--- +title: Codex +weight: 20 +description: | + Use OpenAI Codex in Docker Sandboxes with API key authentication and YOLO + mode configuration. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +This guide covers authentication, configuration, and usage of Codex in a +sandboxed environment. + +Official documentation: [Codex CLI](https://developers.openai.com/codex/cli) + +## Quick start + +Create a sandbox and run Codex for a project directory: + +```console +$ sbx run codex ~/my-project +``` + +The workspace parameter is optional and defaults to the current directory: + +```console +$ cd ~/my-project +$ sbx run codex +``` + +## Authentication + +Codex requires an OpenAI API key. Store your key using +[stored secrets](../security/credentials.md#stored-secrets): + +```console +$ sbx secret set -g openai +``` + +Alternatively, export the `OPENAI_API_KEY` environment variable in your shell +before running the sandbox. See +[Credentials](../security/credentials.md) for details on both methods. + +## Configuration + +Sandboxes don't pick up user-level configuration from your host, such as +`~/.codex`. Only project-level configuration in the working directory is +available inside the sandbox. See +[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) +for workarounds. + +The sandbox runs Codex without approval prompts by default. Pass additional +Codex CLI options after `--`: + +```console +$ sbx run codex --name -- +``` + +## Base image + +Template: `docker/sandbox-templates:codex` + +Preconfigured to run without approval prompts. + +See [Custom environments](custom-environments.md) to pre-install tools or +customize this environment. diff --git a/content/manuals/ai/sandboxes/agents/copilot.md b/content/manuals/ai/sandboxes/agents/copilot.md new file mode 100644 index 0000000000..6ffcc93b7f --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/copilot.md @@ -0,0 +1,70 @@ +--- +title: Copilot +weight: 30 +description: | + Use GitHub Copilot in Docker Sandboxes with GitHub token authentication and + trusted folder configuration. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +This guide covers authentication, configuration, and usage of GitHub Copilot +in a sandboxed environment. + +Official documentation: [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli) + +## Quick start + +Create a sandbox and run Copilot for a project directory: + +```console +$ sbx run copilot ~/my-project +``` + +The workspace parameter is optional and defaults to the current directory: + +```console +$ cd ~/my-project +$ sbx run copilot +``` + +## Authentication + +Copilot requires a GitHub token with Copilot access. Store your token using +[stored secrets](../security/credentials.md#stored-secrets): + +```console +$ echo "$(gh auth token)" | sbx secret set -g github +``` + +Alternatively, export the `GH_TOKEN` or `GITHUB_TOKEN` environment variable in +your shell before running the sandbox. See +[Credentials](../security/credentials.md) for details on both methods. + +## Configuration + +Sandboxes don't pick up user-level configuration from your host. Only +project-level configuration in the working directory is available inside the +sandbox. See +[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) +for workarounds. + +Copilot is configured to trust the workspace directory by default, so it +operates without repeated confirmations for workspace files. + +### Pass options at runtime + +Pass Copilot CLI options after `--`: + +```console +$ sbx run copilot --name -- +``` + +## Base image + +Template: `docker/sandbox-templates:copilot` + +Preconfigured to trust the workspace directory and run without approval prompts. + +See [Custom environments](custom-environments.md) to pre-install tools or +customize this environment. diff --git a/content/manuals/ai/sandboxes/agents/custom-environments.md b/content/manuals/ai/sandboxes/agents/custom-environments.md new file mode 100644 index 0000000000..4bfac553da --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/custom-environments.md @@ -0,0 +1,176 @@ +--- +title: Custom environments +weight: 80 +description: Customize agent sandbox environments or use the shell sandbox for manual setup. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +Every sandbox is customizable — agents install packages, pull images, and +configure tools as they work, and those changes persist for the sandbox's +lifetime. This page covers two things beyond that: a general-purpose shell +sandbox for manual setup, and custom templates that capture a configured +environment into a reusable image so you don't have to set it up again every +time. + +## Shell sandbox + +`sbx run shell` drops you into a Bash login shell inside a sandbox +with no pre-installed agent binary. It's useful for installing and +configuring agents manually, testing custom implementations, or inspecting a +running environment. + +```console +$ sbx run shell ~/my-project +``` + +The workspace path defaults to the current directory. To run a one-off command +instead of an interactive shell, pass it after `--`: + +```console +$ sbx run shell -- -c "echo 'Hello from sandbox'" +``` + +Set your API keys as environment variables so the sandbox proxy can inject them +into API requests automatically. Credentials are never stored inside the VM: + +```console +$ export ANTHROPIC_API_KEY=sk-ant-xxxxx +$ export OPENAI_API_KEY=sk-xxxxx +``` + +Once inside the shell, you can install agents using their standard methods, +for example `npm install -g @continuedev/cli`. For complex setups, build a +[custom template](#custom-templates) instead of installing interactively each +time. + +The shell sandbox uses the `shell` base image — the common base environment +without a pre-installed agent. + +## Custom templates + +Custom templates are reusable sandbox images that extend one of the built-in +agent environments with additional tools and configuration baked in. Instead of +asking the agent to install packages every time, build a template once and +reuse it across sandboxes and team members. + +Templates make sense when multiple people need the same environment, when setup +involves steps that are tedious to repeat, or when you need pinned versions of +specific tools. For one-off work, the default image is fine — ask the agent to +install what's needed. + +> [!NOTE] +> Custom templates customize an existing agent's environment — they don't +> create new agent runtimes. The agent that launches inside the sandbox is +> determined by the base image variant you extend and the agent you specify +> in the `sbx run` command, not by binaries installed in the template. + +### Base images + +All sandbox templates are published as +`docker/sandbox-templates:`. They are based on Ubuntu and run as a +non-root `agent` user with sudo access. Most variants include Git, Docker +CLI, and common development tools like Node.js, Python, Go, and Java. + +| Variant | Agent | +| --------------------- | -------------------------------------------------------------------- | +| `claude-code` | [Claude Code](https://claude.ai/download) | +| `claude-code-minimal` | Claude Code with a minimal toolset (no Node.js, Python, Go, or Java) | +| `codex` | [OpenAI Codex](https://github.com/openai/codex) | +| `copilot` | [GitHub Copilot](https://github.com/github/copilot-cli) | +| `docker-agent` | [Docker Agent](https://github.com/docker/docker-agent) | +| `gemini` | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | +| `kiro` | [Kiro](https://kiro.dev) | +| `opencode` | [OpenCode](https://opencode.ai) | +| `shell` | No agent pre-installed. Use for manual agent setup. | + +Each variant also has a `-docker` version (for example, +`claude-code-docker`) that includes a full Docker Engine running inside the +sandbox. The `-docker` variants are the defaults used by `sbx run` on macOS +and Linux. They run in privileged mode with a dedicated block volume at +`/var/lib/docker`, and `dockerd` starts automatically. + +The block volume defaults to 50 GB and uses a sparse file, so it only +consumes disk space as Docker writes to it. On Windows, the volume is not +sparse and the full 50 GB is allocated at creation time, which increases +startup time. For this reason, the non-docker variants are the default on +Windows. + +To override the volume size, set the `DOCKER_SANDBOXES_DOCKER_SIZE` +environment variable to a size string before starting the sandbox: + +```console +$ DOCKER_SANDBOXES_DOCKER_SIZE=10g sbx run claude +``` + +Use the non-docker variant if you don't need to build or run containers +inside the sandbox and want a lighter, non-privileged environment. Specify +it explicitly with `--template`: + +```console +$ sbx run claude --template docker.io/docker/sandbox-templates:claude-code +``` + +### Build a custom template + +Building a custom template requires [Docker Desktop](https://docs.docker.com/desktop/). + +Write a Dockerfile that extends one of the base images. Pick the variant that +matches the agent you plan to run. For example, extend `claude-code` to +customize a Claude Code environment, or `codex` to customize an OpenAI Codex +environment. + +The following example creates a Claude Code template with Rust and +protocol buffer tools pre-installed: + +```dockerfile +FROM docker/sandbox-templates:claude-code +USER root +RUN apt-get update && apt-get install -y protobuf-compiler +USER agent +RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y +``` + +Use `root` for system-level package installations (`apt-get`), and switch back +to `agent` before installing user-level tools. Tools that install into the +home directory, such as `rustup`, `nvm`, or `pyenv`, must run as `agent` — +otherwise they install under `/root/` and aren't available in the sandbox. + +Build the image and push it to an OCI registry, such as Docker Hub: + +```console +$ docker build -t my-org/my-template:v1 --push . +``` + +> [!NOTE] +> The Docker daemon used by Docker Sandboxes pulls templates from a registry +> directly; it doesn't share the image store of your local Docker daemon on +> the host. + +Unless you use the permissive `allow-all` network policy, you may also need to +allow-list any domains that your custom tools depend on: + +```console +$ sbx policy allow network "*.example.com:443,example.com:443" +``` + +Then run a sandbox with your template. The agent you specify must match the +base image variant your template extends: + +```console +$ sbx run --template docker.io/my-org/my-template:v1 claude +``` + +Because this template extends the `claude-code` base image, you run it with +`claude`. If you extend `codex`, use `codex`; if you extend `shell`, use +`shell` (which drops you into a Bash shell with no agent). + +> [!NOTE] +> Unlike Docker commands, `sbx` does not automatically resolve the Docker Hub +> domain (`docker.io`) in image references. + +### Template caching + +Template images are cached locally. The first use pulls from the registry; +subsequent sandboxes reuse the cache. Cached images persist across sandbox +creation and deletion, and are cleared when you run `sbx reset`. diff --git a/content/manuals/ai/sandboxes/agents/docker-agent.md b/content/manuals/ai/sandboxes/agents/docker-agent.md new file mode 100644 index 0000000000..e6cb9df2eb --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/docker-agent.md @@ -0,0 +1,72 @@ +--- +title: Docker Agent +weight: 70 +description: | + Use Docker Agent in Docker Sandboxes with multi-provider authentication + supporting OpenAI, Anthropic, and more. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +Official documentation: [Docker Agent](https://docs.docker.com/ai/docker-agent/) + +## Quick start + +Create a sandbox and run Docker Agent for a project directory: + +```console +$ sbx run docker-agent ~/my-project +``` + +The workspace parameter defaults to the current directory, so +`sbx run docker-agent` from inside your project works too. + +## Authentication + +Docker Agent supports multiple providers. Store keys for the providers you want +to use with [stored secrets](../security/credentials.md#stored-secrets): + +```console +$ sbx secret set -g openai +$ sbx secret set -g anthropic +$ sbx secret set -g google +$ sbx secret set -g xai +$ sbx secret set -g nebius +$ sbx secret set -g mistral +``` + +You only need to configure the providers you want to use. Docker Agent detects +available credentials and routes requests to the appropriate provider. + +Alternatively, export the environment variables (`OPENAI_API_KEY`, +`ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `XAI_API_KEY`, `NEBIUS_API_KEY`, +`MISTRAL_API_KEY`) in your shell before running the sandbox. See +[Credentials](../security/credentials.md) for details on both methods. + +## Configuration + +Sandboxes don't pick up user-level configuration from your host. Only +project-level configuration in the working directory is available inside the +sandbox. See +[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) +for workarounds. + +The sandbox runs Docker Agent without approval prompts by default. Pass +additional CLI options after `--`: + +```console +$ sbx run docker-agent --name my-sandbox -- +``` + +For example, to specify a custom `agent.yml` configuration file: + +```console +$ sbx run docker-agent -- agent.yml +``` + +## Base image + +The sandbox uses `docker/sandbox-templates:docker-agent` and launches Docker +Agent without approval prompts by default. See +[Custom environments](custom-environments.md) to build your own image on top of +this base. diff --git a/content/manuals/ai/sandboxes/agents/gemini.md b/content/manuals/ai/sandboxes/agents/gemini.md new file mode 100644 index 0000000000..6e40b52e09 --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/gemini.md @@ -0,0 +1,75 @@ +--- +title: Gemini +weight: 40 +description: | + Use Google Gemini in Docker Sandboxes with proxy-managed authentication and + API key configuration. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +This guide covers authentication, configuration, and usage of Google Gemini in +a sandboxed environment. + +Official documentation: [Gemini CLI](https://geminicli.com/docs/) + +## Quick start + +Create a sandbox and run Gemini for a project directory: + +```console +$ sbx run gemini ~/my-project +``` + +The workspace parameter is optional and defaults to the current directory: + +```console +$ cd ~/my-project +$ sbx run gemini +``` + +## Authentication + +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): + +```console +$ sbx secret set -g google +``` + +Alternatively, export the `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment +variable in your shell before running the sandbox. See +[Credentials](../security/credentials.md) for details on both methods. + +**Google account**: If no API key is set, Gemini prompts you to sign in +interactively when it starts. Interactive authentication is scoped to the +sandbox and doesn't persist if you remove and recreate it. + +## Configuration + +Sandboxes don't pick up user-level configuration from your host, such as +`~/.gemini`. Only project-level configuration in the working directory is +available inside the sandbox. See +[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) +for workarounds. + +The sandbox runs Gemini without approval prompts by default and disables +Gemini's built-in sandbox tool (since the sandbox itself provides isolation). +Pass additional Gemini CLI options after `--`: + +```console +$ sbx run gemini --name -- +``` + +## Base image + +Template: `docker/sandbox-templates:gemini` + +Gemini is configured to disable its built-in OAuth flow. Authentication is +managed through the proxy with API keys. Preconfigured to run without +approval prompts. + +See [Custom environments](custom-environments.md) to pre-install tools or +customize this environment. diff --git a/content/manuals/ai/sandboxes/agents/kiro.md b/content/manuals/ai/sandboxes/agents/kiro.md new file mode 100644 index 0000000000..66ffcefc18 --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/kiro.md @@ -0,0 +1,98 @@ +--- +title: Kiro +weight: 50 +description: | + Use Kiro in Docker Sandboxes with device flow authentication for interactive + AI-assisted development. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +This guide covers authentication, configuration, and usage of Kiro in a +sandboxed environment. + +Official documentation: [Kiro CLI](https://kiro.dev/docs/cli/) + +## Quick start + +Create a sandbox and run Kiro for a project directory: + +```console +$ sbx run kiro ~/my-project +``` + +The workspace parameter is optional and defaults to the current directory: + +```console +$ cd ~/my-project +$ sbx run kiro +``` + +On first run, Kiro prompts you to authenticate using device flow. + +## Authentication + +Kiro uses device flow authentication, which requires interactive login through +a web browser. This method provides secure authentication without storing API +keys directly. + +### Device flow login + +When you first run Kiro, it prompts you to authenticate: + +1. Kiro displays a URL and a verification code +2. Open the URL in your web browser +3. Enter the verification code +4. Complete the authentication flow in your browser +5. Return to the terminal - Kiro proceeds automatically + +The authentication session is persisted in the sandbox and doesn't require +repeated login unless you destroy and recreate the sandbox. + +### Manual login + +You can trigger the login flow manually: + +```console +$ sbx run kiro --name -- login --use-device-flow +``` + +This command initiates device flow authentication without starting a coding +session. + +### Authentication persistence + +Kiro stores authentication state in `~/.local/share/kiro-cli/data.sqlite3` +inside the sandbox. This database persists as long as the sandbox exists. If +you destroy the sandbox, you'll need to authenticate again when you recreate +it. + +## Configuration + +Sandboxes don't pick up user-level configuration from your host. Only +project-level configuration in the working directory is available inside the +sandbox. See +[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) +for workarounds. + +Kiro requires minimal configuration. The agent runs with trust-all-tools mode +by default, which lets it execute commands without repeated approval +prompts. + +### Pass options at runtime + +Pass Kiro CLI options after `--`: + +```console +$ sbx run kiro --name -- +``` + +## Base image + +Template: `docker/sandbox-templates:kiro` + +Preconfigured to run without approval prompts. Authentication state is +persisted across sandbox restarts. + +See [Custom environments](custom-environments.md) to pre-install tools or +customize this environment. diff --git a/content/manuals/ai/sandboxes/agents/opencode.md b/content/manuals/ai/sandboxes/agents/opencode.md new file mode 100644 index 0000000000..2fe81f227d --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/opencode.md @@ -0,0 +1,86 @@ +--- +title: OpenCode +weight: 60 +description: | + Use OpenCode in Docker Sandboxes with multi-provider authentication and TUI + interface for AI development. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +This guide covers authentication, configuration, and usage of OpenCode in a +sandboxed environment. + +Official documentation: [OpenCode](https://opencode.ai/docs) + +## Quick start + +Create a sandbox and run OpenCode for a project directory: + +```console +$ sbx run opencode ~/my-project +``` + +The workspace parameter is optional and defaults to the current directory: + +```console +$ cd ~/my-project +$ sbx run opencode +``` + +OpenCode launches a TUI (text user interface) where you can select your +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): + +```console +$ sbx secret set -g openai +$ sbx secret set -g anthropic +$ sbx secret set -g google +$ sbx secret set -g xai +$ sbx secret set -g groq +$ sbx secret set -g aws +``` + +You only need to configure the providers you want to use. OpenCode detects +available credentials and offers those providers in the TUI. + +You can also use environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, +`GOOGLE_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `AWS_ACCESS_KEY_ID`). See +[Credentials](../security/credentials.md) for details on both methods. + +## Configuration + +Sandboxes don't pick up user-level configuration from your host. Only +project-level configuration in the working directory is available inside the +sandbox. See +[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) +for workarounds. + +OpenCode uses a TUI interface and doesn't require extensive configuration +files. The agent prompts you to select a provider when it starts, and you can +switch providers during a session. + +### TUI mode + +OpenCode launches in TUI mode by default. The interface shows: + +- Available LLM providers (based on configured credentials) +- Current conversation history +- File operations and tool usage +- Real-time agent responses + +Use keyboard shortcuts to navigate the interface and interact with the agent. + +## Base image + +Template: `docker/sandbox-templates:opencode` + +OpenCode supports multiple LLM providers with automatic credential injection +through the sandbox proxy. + +See [Custom environments](custom-environments.md) to pre-install tools or +customize this environment. diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md new file mode 100644 index 0000000000..5499a652b2 --- /dev/null +++ b/content/manuals/ai/sandboxes/architecture.md @@ -0,0 +1,69 @@ +--- +title: Architecture +weight: 40 +description: Technical architecture of Docker Sandboxes; workspace mounting, storage, networking, and sandbox lifecycle. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +This page explains how Docker Sandboxes work under the hood. For the security +properties of the architecture, see [Sandbox isolation](security/isolation.md). + +## Workspace mounting + +Your workspace is mounted directly into the sandbox through a filesystem +passthrough. The sandbox sees your actual host files, so changes in either +direction are instant with no sync process involved. + +Your workspace is mounted at the same absolute path as on your host. Preserving +absolute paths means error messages, configuration files, and build outputs all +reference paths you can find on your host. The agent sees exactly the directory +structure you see, which reduces confusion when debugging or reviewing changes. + +## Storage and persistence + +When you create a sandbox, everything inside it persists until you remove it: +Docker images and containers built or pulled by the agent, installed packages, +agent state and history, and workspace changes. + +Sandboxes are isolated from each other. Each one maintains its own Docker +daemon state, image cache, and package installations. Multiple sandboxes don't +share images or layers. + +Each sandbox consumes disk space for its VM image, Docker images, container +layers, and volumes, and this grows as you build images and install packages. + +## Networking + +All outbound traffic from the sandbox routes through an HTTP/HTTPS proxy on +your host. Agents are configured to use the proxy automatically. The proxy +enforces [network access policies](security/policy.md) and handles +[credential injection](security/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. + +## Lifecycle + +`sbx run` initializes a VM with a workspace for a specified agent and starts +the agent. You can stop and restart without recreating the VM, preserving +installed packages and Docker images. + +Sandboxes persist until explicitly removed. Stopping an agent doesn't delete +the VM; environment setup carries over between runs. Use `sbx rm` to delete +the sandbox, its VM, and all of its contents. If the sandbox used +`--branch`, the worktree directories and their branches are also removed. + +## Comparison to alternatives + +| Approach | Isolation | Docker access | Use case | +| --------------------------------------------------- | -------------------- | ------------------ | ------------------ | +| Sandboxes (microVMs) | Full (hypervisor) | Isolated daemon | Autonomous agents | +| Container with socket mount | Partial (namespaces) | Shared host daemon | Trusted tools | +| [Docker-in-Docker](https://hub.docker.com/_/docker) | Partial (privileged) | Nested daemon | CI/CD pipelines | +| Host execution | None | Host daemon | Manual development | + +Sandboxes trade higher resource overhead (a VM plus its own daemon) for +complete isolation. Use containers when you need lightweight packaging without +Docker access. Use sandboxes when you need to give something autonomous full +Docker capabilities without trusting it with your host environment. diff --git a/content/manuals/ai/sandboxes/docker-desktop.md b/content/manuals/ai/sandboxes/docker-desktop.md index 16c27267b7..4aa0e61823 100644 --- a/content/manuals/ai/sandboxes/docker-desktop.md +++ b/content/manuals/ai/sandboxes/docker-desktop.md @@ -13,7 +13,7 @@ convenience integration with limited features compared to the standalone sandbox CLI. > [!NOTE] -> The standalone `ds` CLI provides more features, more flexibility, and doesn't +> The standalone `sbx` CLI provides more features, more flexibility, and doesn't > require Docker Desktop. If you're setting up sandboxed agents for the first > time, consider using the standalone CLI instead. @@ -47,16 +47,16 @@ Replace `claude` with a different [agent](#supported-agents) if needed. ## Supported agents -| Agent | Command | Notes | -| --------------------------------- | ---------- | ------------------------------------ | -| Claude Code | `claude` | Most tested implementation | -| Codex | `codex` | | -| Copilot | `copilot` | | -| Gemini | `gemini` | | -| [Docker Agent](/ai/docker-agent/) | `cagent` | Also available as a standalone tool | -| Kiro | `kiro` | | -| OpenCode | `opencode` | | -| Custom shell | `shell` | Minimal environment for manual setup | +| Agent | Command | Notes | +| --------------------------------- | -------------- | ------------------------------------ | +| Claude Code | `claude` | Most tested implementation | +| Codex | `codex` | | +| Copilot | `copilot` | | +| Gemini | `gemini` | | +| [Docker Agent](/ai/docker-agent/) | `docker-agent` | Also available as a standalone tool | +| Kiro | `kiro` | | +| OpenCode | `opencode` | | +| Custom shell | `shell` | Minimal environment for manual setup | All agents are experimental. The agent type is specified when creating a sandbox and can't be changed later. @@ -110,9 +110,12 @@ $ docker sandbox run -- --continue ## Architecture Each sandbox is a lightweight microVM with its own kernel, using your system's -native virtualization (macOS virtualization.framework, Windows Hyper-V). Every -sandbox includes a private Docker daemon, so `docker build` and -`docker compose up` run inside the sandbox without affecting your host. +native virtualization (macOS virtualization.framework, Windows Hyper-V). The +default agent templates include a private Docker daemon, so `docker build` and +`docker compose up` run inside the sandbox without affecting your host. On +Windows, the Docker daemon is not included by default. See +[Troubleshooting](troubleshooting.md#docker-not-available-inside-the-sandbox-on-windows) +for a workaround. ```plaintext Host system diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md new file mode 100644 index 0000000000..5c500c2095 --- /dev/null +++ b/content/manuals/ai/sandboxes/faq.md @@ -0,0 +1,104 @@ +--- +title: FAQ +weight: 70 +description: Frequently asked questions about Docker Sandboxes. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +## Why do I need to sign in? + +Docker Sandboxes is built around the idea that you and your agents are a team. +Signing in gives each sandbox a verified identity, which lets Docker: + +- **Tie sandboxes to a real person.** Governance matters when agents can build + containers, install packages, and push code. Your Docker identity is the + anchor. +- **Enable team features down the road.** Shared environments, org-level + policies, audit logs. These all need a concept of "who," and building that in + later would be worse for everyone. +- **Authenticate against Docker infrastructure.** Sandboxes pull images, run + daemons, and talk to Docker services. A Docker account makes that seamless. + +Your Docker account email is only used for authentication, not marketing. + +## Does the CLI collect telemetry? + +The `sbx` CLI collects basic usage data about CLI invocations: + +- Which subcommand you ran +- Whether it succeeded or failed +- How long it took +- If you're signed in, your Docker username is included + +Docker Sandboxes doesn't monitor sessions, read your prompts, or access your +code. Your code stays in the sandbox and on your host. + +To opt out of all analytics, set the `SBX_NO_TELEMETRY` environment variable: + +```console +$ export SBX_NO_TELEMETRY=1 +``` + +## How do I set custom environment variables inside a sandbox? + +The [`sbx secret`](/reference/cli/sbx/secret/) command only supports a fixed set +of [services](security/credentials.md#supported-services) (Anthropic, OpenAI, +GitHub, and others). If your agent needs an environment variable that isn't +tied to a supported service, such as `BRAVE_API_KEY` or a custom internal +token, write it to `/etc/sandbox-persistent.sh` inside the sandbox. This +file is sourced on every shell login, so the variable persists across agent +sessions for the sandbox's lifetime. + +Use `sbx exec` to append the export: + +```console +$ sbx exec -d bash -c "echo 'export BRAVE_API_KEY=your_key' >> /etc/sandbox-persistent.sh" +``` + +The `bash -c` wrapper is required so the `>>` redirect runs inside the +sandbox instead of on your host. + +> [!NOTE] +> Unlike `sbx secret`, which injects credentials through a host-side proxy +> without exposing them to the agent, this approach stores the value inside +> the sandbox. The agent process can read it directly. Only use this for +> credentials where proxy-based injection isn't available. + +To verify the variable is set, open a shell in the sandbox: + +```console +$ sbx exec -it bash +$ echo $BRAVE_API_KEY +``` + +## How do I know if my agent is running in a sandbox? + +Ask the agent. The agent can see whether or not it's running inside a sandbox. +In Claude Code, use the `/btw` slash command to ask without interrupting an +in-progress task: + +```text +/btw are you running in a sandbox? +``` + +## Why doesn't the sandbox use my user-level agent configuration? + +Sandboxes don't pick up user-level agent configuration from your host. This +includes directories like `~/.claude` for Claude Code or `~/.codex` for Codex, +where hooks, skills, and other settings are stored. Only project-level +configuration in the working directory is available inside the sandbox. + +To make configuration available in a sandbox, copy or move what you need into +your project directory before starting a session: + +```console +$ cp -r ~/.claude/skills .claude/skills +``` + +Don't use symlinks — a sandboxed agent can't follow symlinks to paths outside +the sandbox. + +Collocating skills and other agent configuration with the project itself is a +good practice regardless of sandboxes. It's versioned alongside the code and +evolves with the project as it changes. diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md new file mode 100644 index 0000000000..4cbc1523fd --- /dev/null +++ b/content/manuals/ai/sandboxes/get-started.md @@ -0,0 +1,110 @@ +--- +title: Get started with Docker Sandboxes +linkTitle: Get started +weight: 10 +description: Install the sbx CLI and run an AI coding agent in an isolated sandbox. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each +sandbox gets its own Docker daemon, filesystem, and network — the agent can +build containers, install packages, and modify files without touching your host +system. + +## Prerequisites + +- macOS (Apple silicon) or Windows (x86_64, Windows 11 required) +- If you're on Windows, enable Windows Hypervisor Platform (requires + elevated permissions): + ```powershell + Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All + ``` +- An API key or authentication method for the agent you want to use. Most + agents require an API key for their model provider (Anthropic, OpenAI, + Google, and others). See the [agent pages](agents/) for provider-specific + instructions, and [Credentials](security/credentials.md) for how to store + and manage keys. + +Docker Desktop is not required to use `sbx`. + +## Install and sign in + +{{< tabs >}} +{{< tab name="macOS" >}} + +```console +$ brew install docker/tap/sbx +$ sbx login +``` + +{{< /tab >}} +{{< tab name="Windows" >}} + +```powershell +> winget install -h Docker.sbx +> sbx login +``` + +{{< /tab >}} +{{< /tabs >}} + +`sbx login` opens a browser for Docker OAuth. On first login (and after `sbx +policy reset`), the CLI prompts you to choose a default network policy for your +sandboxes: + +```plaintext +Choose a default network policy: + + 1. Open — All network traffic allowed, no restrictions. + 2. Balanced — Default deny, with common dev sites allowed. + 3. Locked Down — All network traffic blocked unless you allow it. + +Use ↑/↓ to navigate, Enter to select, or press 1–3. +``` + +See [Policies](security/policy.md) for a full description of each option. + +> [!NOTE] +> See the [FAQ](faq.md) for details on why sign-in is required and what +> happens with your data. + +## Run your first sandbox + +Pick a project directory and launch an agent with [`sbx run`](/reference/cli/sbx/run/): + +```console +$ cd ~/my-project +$ sbx run claude +``` + +Replace `claude` with the agent you want to use — see [Agents](agents/) for the +full list. + +The first run takes a little longer while the agent image is pulled. +Subsequent runs reuse the cached image and start in seconds. + +You can check what's running at any time: + +```console +$ sbx ls +NAME STATUS UPTIME +claude-my-project running 12s +``` + +The agent can modify files in your project directory, so review changes before +merging. See [Workspace trust](security/workspace.md) for details. + +> [!CAUTION] +> Your network policy controls what the sandbox can reach. With **Locked +> Down**, even your model provider API is blocked. With **Balanced**, a broad +> set of common development services is allowed by default — add other hosts +> with `sbx policy allow`. See [Policies](security/policy.md) for details. + +## Next steps + +- [Usage guide](usage.md) — common patterns and workflows +- [Agents](agents/) — supported agents and configuration +- [Custom environments](agents/custom-environments.md) — build your own sandbox + images +- [Policies](security/policy.md) — control outbound access diff --git a/content/manuals/ai/sandboxes/images/sbx-security.png b/content/manuals/ai/sandboxes/images/sbx-security.png new file mode 100644 index 0000000000..0f86c436c5 Binary files /dev/null and b/content/manuals/ai/sandboxes/images/sbx-security.png differ diff --git a/content/manuals/ai/sandboxes/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md new file mode 100644 index 0000000000..7cdcbb3924 --- /dev/null +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -0,0 +1,91 @@ +--- +title: Security model +linkTitle: Security model +weight: 50 +description: Trust boundaries, isolation layers, and security properties of Docker Sandboxes. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +Docker Sandboxes run AI agents in microVMs so they can execute code, install +packages, and use tools without accessing your host system. Multiple isolation +layers protect your host system. + +## Trust boundaries + +The primary trust boundary is the microVM. The agent has full control inside +the VM, including sudo access. The VM boundary prevents the agent from reaching +anything on your host except what is explicitly shared. + +What crosses the boundary into the VM: + +- **Workspace directory:** mounted into the VM with read-write access. With + the default direct mount, changes the agent makes appear on your host + immediately. +- **Credentials:** the host-side proxy injects authentication headers into + outbound HTTP requests. The raw credential values never enter the VM. +- **Network access:** HTTP and HTTPS requests to + [allowed domains](defaults/) are proxied through the host. + +What crosses the boundary back to the host: + +- **Workspace file changes:** visible on your host in real time with the + default direct mount. +- **HTTP/HTTPS requests:** sent to allowed domains through the host proxy. + +Everything else is blocked. The agent cannot access your host filesystem +(outside the workspace), your host Docker daemon, your host network or +localhost, other sandboxes, or any domain not in the allow list. Raw TCP, UDP, +and ICMP are blocked at the network layer. + +![Sandbox security model showing the hypervisor boundary between the sandbox VM and the host system. The workspace directory is shared read-write. The agent process, Docker engine, packages, and VM filesystem are inside the VM. Host filesystem, processes, Docker engine, and network are outside the VM and not accessible. A proxy enforces allow/deny policies and injects credentials into outbound requests.](../images/sbx-security.png) + +## Isolation layers + +The sandbox security model has four layers. See +[Isolation layers](isolation/) for technical details on each. + +- **Hypervisor isolation:** separate kernel per sandbox. No shared memory or + processes with the host. +- **Network isolation:** all HTTP/HTTPS traffic proxied through the host. + [Deny-by-default policy](defaults/). Non-HTTP protocols blocked entirely. +- **Docker Engine isolation:** each sandbox has its own Docker Engine with no + path to the host daemon. +- **Credential isolation:** API keys are injected into HTTP headers by the + host-side proxy. Credential values never enter the VM. + +## What the agent can do inside the sandbox + +Inside the VM, the agent has full privileges: sudo access, package installation, +a private Docker Engine, and read-write access to the workspace. Installed +packages, Docker images, and other VM state persist across restarts. See +[Default security posture](defaults/) for the full breakdown of what is +permitted and what is blocked. + +## What is not isolated by default + +The sandbox isolates the agent from your host system, but the agent's actions +can still affect you through the shared workspace and allowed network channels. + +**Workspace changes are live on your host.** The agent edits the same files you +see on your host. This includes files that execute implicitly during normal +development: Git hooks, CI configuration, IDE task configs, `Makefile`, +`package.json` scripts, and similar build files. Review changes before running +any modified code. Note that Git hooks live inside `.git/` and do not appear in +`git diff` output. Check them separately. +See [Workspace trust](workspace/). + +**Default allowed domains include broad wildcards.** Some defaults like +`*.googleapis.com` cover many services beyond AI APIs. Run `sbx policy ls` to +see the full list of active rules, and remove entries you don't need. See +[Default security posture](defaults/). + +## Learn more + +- [Isolation layers](isolation/): how hypervisor, network, Docker, and + credential isolation work +- [Default security posture](defaults/): what a fresh sandbox permits and + blocks +- [Credentials](credentials/): how to provide and manage API keys +- [Policies](policy/): how to customize network access rules +- [Workspace trust](workspace/): what to review after an agent session diff --git a/content/manuals/ai/sandboxes/security/credentials.md b/content/manuals/ai/sandboxes/security/credentials.md new file mode 100644 index 0000000000..2279ad7dd3 --- /dev/null +++ b/content/manuals/ai/sandboxes/security/credentials.md @@ -0,0 +1,147 @@ +--- +title: Credentials +weight: 20 +description: How Docker Sandboxes handle API keys and authentication credentials for sandboxed agents. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +Most agents need an API key for their model provider. An HTTP/HTTPS proxy on +your host intercepts outbound API requests from the sandbox and injects the +appropriate authentication headers before forwarding each request. Your +credentials stay on the host and are never stored inside the sandbox VM. For +how this works as a security layer, see +[Credential isolation](isolation.md#credential-isolation). + +There are two ways to provide credentials: + +- **Stored secrets** (recommended): saved in your OS keychain, encrypted and + persistent across sessions. +- **Environment variables:** read from your current shell session. This works + but is less secure on the host side, since environment variables are visible + to other processes running as your user. + +If both are set for the same service, the stored secret takes precedence. For +multi-provider agents (OpenCode, Docker Agent), the proxy automatically selects the +correct credentials based on the API endpoint being called. See individual +[agent pages](../agents/) for provider-specific details. + +## Stored secrets + +The `sbx secret` command stores credentials in your OS keychain so you don't +need to export environment variables in every terminal session. When a sandbox +starts, the proxy looks up stored secrets and uses them to authenticate API +requests on behalf of the agent. The secret is never exposed directly to the +agent. + +### Store a secret + +```console +$ sbx secret set -g anthropic +``` + +This prompts you for the secret value interactively. The `-g` flag stores the +secret globally so it's available to all sandboxes. To scope a secret to a +specific sandbox instead: + +```console +$ sbx secret set my-sandbox openai +``` + +> [!NOTE] +> A sandbox-scoped secret takes effect immediately, even if the sandbox is +> running. A global secret (`-g`) only applies when a sandbox is created. If +> you set or change a global secret while a sandbox is running, recreate the +> sandbox for the new value to take effect. + +You can also pipe in a value for non-interactive use: + +```console +$ echo "$ANTHROPIC_API_KEY" | sbx secret set -g anthropic +``` + +### Supported services + +Each service name maps to a set of environment variables the proxy checks and +the API domains it authenticates requests to: + +| Service | Environment variables | API domains | +| ----------- | -------------------------------------------- | ----------------------------------- | +| `anthropic` | `ANTHROPIC_API_KEY` | `api.anthropic.com` | +| `aws` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | AWS Bedrock endpoints | +| `github` | `GH_TOKEN`, `GITHUB_TOKEN` | `api.github.com`, `github.com` | +| `google` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | `generativelanguage.googleapis.com` | +| `groq` | `GROQ_API_KEY` | `api.groq.com` | +| `mistral` | `MISTRAL_API_KEY` | `api.mistral.ai` | +| `nebius` | `NEBIUS_API_KEY` | `api.studio.nebius.ai` | +| `openai` | `OPENAI_API_KEY` | `api.openai.com` | +| `xai` | `XAI_API_KEY` | `api.x.ai` | + +When you store a secret with `sbx secret set -g `, the proxy uses it +the same way it would use the corresponding environment variable. You don't +need to set both. + +### List and remove secrets + +List all stored secrets: + +```console +$ sbx secret ls +SCOPE SERVICE SECRET +(global) github gho_GCaw4o****...****43qy +``` + +Remove a secret: + +```console +$ sbx secret rm -g github +``` + +> [!NOTE] +> Running `sbx reset` deletes all stored secrets along with all sandbox state. +> You'll need to re-add your secrets after a reset. + +### GitHub token + +The `github` service gives the agent access to the `gh` CLI inside the +sandbox. Pass your existing GitHub CLI token: + +```console +$ echo "$(gh auth token)" | sbx secret set -g github +``` + +This is useful for agents that create pull requests, open issues, or interact +with GitHub APIs on your behalf. + +## Environment variables + +As an alternative to stored secrets, export the relevant environment variable +in your shell before running a sandbox: + +```console +$ export ANTHROPIC_API_KEY=sk-ant-api03-xxxxx +$ sbx run claude +``` + +The proxy reads the variable from your terminal session. See individual +[agent pages](../agents/) for the variable names each agent expects. + +## Best practices + +- Use [stored secrets](#stored-secrets) over environment variables. The OS + keychain encrypts credentials at rest and controls access, while environment + variables are plaintext in your shell. +- Don't set API keys manually inside the sandbox. Credentials stored in + environment variables or configuration files inside the VM are readable by + the agent process directly. +- For Claude Code, the interactive OAuth flow is another secure option: the + proxy handles authentication without exposing the token inside the sandbox. + Leave `ANTHROPIC_API_KEY` unset to use OAuth. + +## Custom templates and placeholder values + +When building custom templates or installing agents manually in a shell +sandbox, some agents require environment variables like `OPENAI_API_KEY` to be +set before they start. Set these to placeholder values (e.g. `proxy-managed`) +if needed. The proxy injects actual credentials regardless of the environment +variable value. diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md new file mode 100644 index 0000000000..fd9a1286f3 --- /dev/null +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -0,0 +1,68 @@ +--- +title: Default security posture +linkTitle: Defaults +weight: 15 +description: What a sandbox permits and blocks before you change any settings. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +A sandbox created with `sbx run` and no additional flags or blueprints has +the following security posture. + +## Network defaults + +All outbound HTTP and HTTPS traffic is blocked unless an explicit rule allows +it (deny-by-default). All non-HTTP protocols (raw TCP, UDP including DNS, and +ICMP) are blocked at the network layer. Traffic to private IP ranges, loopback +addresses, and link-local addresses is also blocked. + +Run `sbx policy ls` to see the active allow rules for your installation. To +customize network access, see [Policies](policy.md). + +## Workspace defaults + +Sandboxes use a direct mount by default. The agent sees and modifies your +working tree directly, and changes appear on your host immediately. + +The agent can read, write, and delete any file within the workspace directory, +including hidden files, configuration files, build scripts, and Git hooks. +See [Workspace trust](workspace.md) for what to review after an agent session. + +## Credential defaults + +No credentials are available to the sandbox unless you provide them using +`sbx secret` or environment variables. When credentials are provided, the +host-side proxy injects them into outbound HTTP headers. The agent cannot +read the raw credential values. + +See [Credentials](credentials.md) for setup instructions. + +## Agent capabilities inside the sandbox + +The agent runs with full control inside the sandbox VM: + +- `sudo` access (the agent runs as a non-root user with sudo privileges) +- A private Docker Engine for building images and running containers +- Package installation through `apt`, `pip`, `npm`, and other package managers +- Full read and write access to the VM filesystem + +Everything the agent installs or creates inside the VM, including packages, +Docker images, and configuration changes, persists across stop and restart +cycles. When you remove the sandbox with `sbx rm`, the VM and its contents +are deleted. Only workspace files remain on the host. + +## What is blocked by default + +The following are blocked for all sandboxes and cannot be changed through +policy configuration: + +- Host filesystem access outside the workspace directory +- Host Docker daemon +- Host network and localhost +- Communication between sandboxes +- Raw TCP, UDP, and ICMP connections +- Traffic to private IP ranges and link-local addresses + +Outbound HTTP/HTTPS to domains not in the allow list is also blocked by +default, but you can add allow rules with `sbx policy allow`. diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md new file mode 100644 index 0000000000..91dfaefba3 --- /dev/null +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -0,0 +1,86 @@ +--- +title: Isolation layers +weight: 10 +description: How Docker Sandboxes isolate AI agents using hypervisor, network, Docker Engine, and credential boundaries. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +AI coding agents need to execute code, install packages, and run tools on +your behalf. Docker Sandboxes run each agent in its own microVM with four +isolation layers: hypervisor, network, Docker Engine, and credential proxy. + +## Hypervisor isolation + +Every sandbox runs inside a lightweight microVM with its own Linux kernel. +Unlike containers, which share the host kernel, a sandbox VM cannot access host +processes, files, or resources outside its defined boundaries. + +- **Process isolation:** separate kernel per sandbox; processes inside the VM + are invisible to your host and to other sandboxes +- **Filesystem isolation:** only your workspace directory is 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 + everything inside it is deleted + +The agent runs as a non-root user with sudo privileges inside the VM. The +hypervisor boundary is the isolation control, not in-VM privilege separation. + +## Network isolation + +Each sandbox has its own isolated network. Sandboxes cannot communicate with +each other and cannot reach your host's localhost. There is no shared network +between sandboxes or between a sandbox and your host. + +All HTTP and HTTPS traffic leaving a sandbox passes through a proxy on your +host that enforces the [network policy](policy.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. + +Raw TCP connections, UDP, and ICMP are blocked at the network layer. DNS +resolution is handled by the proxy; the sandbox cannot make raw DNS queries. +Traffic to private IP ranges, loopback, and link-local addresses is also +blocked. Only domains explicitly listed in the policy are reachable. + +For the default set of allowed domains, see +[Default security posture](defaults.md). + +## Docker Engine isolation + +Agents often need to build images, run containers, and use Docker Compose. +Mounting your host Docker socket into a container would give the agent full +access to your environment. + +Docker Sandboxes avoid this by running a separate [Docker +Engine](https://docs.docker.com/engine/) inside the sandbox environment, isolated from +your host. When the agent runs `docker build` or `docker compose up`, those +commands execute against that engine. The agent has no path to your host Docker +daemon. + +```plaintext +Host system + ├── Host Docker daemon + │ └── Your containers and images + │ + └── Sandbox Docker engine (isolated from host) + ├── [VM] Agent container — sandbox 1 + │ └── [VM] Containers created by agent + └── [VM] Agent container — sandbox 2 + └── [VM] Containers created by agent +``` + +## Credential isolation + +Most agents need API keys for their model provider. Rather than passing keys +into the sandbox, the host-side proxy intercepts outbound API requests and +injects authentication headers before forwarding each request. + +Credential values are never stored inside the VM. They are not available as +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). diff --git a/content/manuals/ai/sandboxes/security/policy.md b/content/manuals/ai/sandboxes/security/policy.md new file mode 100644 index 0000000000..6001a0dd2f --- /dev/null +++ b/content/manuals/ai/sandboxes/security/policy.md @@ -0,0 +1,293 @@ +--- +title: Policies +weight: 30 +description: Configure network access and filesystem rules for sandboxes. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +Sandboxes are [network-isolated](isolation.md) from your host and from each +other. A policy system controls what a sandbox can access — which external +hosts it can reach over the network, and which host paths it can mount as +workspaces. + +Policies can be set at two levels: + +- **Organization policies** {{< badge color=blue text="Limited Access" >}} — configured by admins in the + [Docker Admin Console](https://app.docker.com/admin) under AI governance + settings. These apply to all sandboxes across the organization. +- **Local policies** — configured by individual users with the `sbx policy` + command. These apply to all sandboxes on the local machine. + +If your organization has enabled governance, organization policies take +precedence over local rules and can't be overridden locally. See +[Precedence](#precedence) for the full evaluation model. + +## Organization policies {tier="Limited Access"} + +> [!NOTE] +> Organization governance is a Limited Access feature. Contact your Docker +> account team to request access. + +Organization admins can centrally manage policies through the +[Docker Admin Console](https://app.docker.com/admin). Navigate to your +organization settings and enable **Manage AI governance**. + +Once enabled, the policies defined in the Admin Console apply to all +sandboxes across the organization, regardless of any local policies +configured with `sbx policy`. + +### Local extensions to organization policy + +Organization policy is the baseline for all sandboxes in your organization. +Admins can optionally permit users to extend it locally by enabling the +**User defined** setting in AI governance settings. When enabled, users can +add hosts to the allowlist from their own machine using `sbx policy allow network`. + +Local extensions can only expand access within what the organization permits. +They can't override organization-level deny rules. + +## Network policies + +The only way traffic can leave a sandbox is through an HTTP/HTTPS proxy on +your host, which enforces access rules on every outbound request. + +### Initial policy selection + +On first start, and after running `sbx policy reset`, the daemon prompts you to +choose a network policy: + +```plaintext +Choose a default network policy: + + 1. Open — All network traffic allowed, no restrictions. + 2. Balanced — Default deny, with common dev sites allowed. + 3. Locked Down — All network traffic blocked unless you allow it. + + Use ↑/↓ to navigate, Enter to select, or press 1–3. +``` + +| Policy | Description | +| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Open | All outbound traffic is allowed. No restrictions. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`. | +| Balanced | Default deny, with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. You can extend this with `sbx policy allow`. | +| Locked Down | All outbound traffic is blocked, including model provider APIs (for example, `api.anthropic.com`). You must explicitly allow everything you need. | + +You can change your effective policy at any time using `sbx policy allow` and +`sbx policy deny`, or start over by running `sbx policy reset`. + +### Non-interactive environments + +In non-interactive environments such as CI pipelines or headless servers, the +interactive prompt can't be displayed. Use `sbx policy set-default` to set the +default network policy before running any other `sbx` commands: + +```console +$ sbx policy set-default balanced +``` + +Available values are `allow-all`, `balanced`, and `deny-all`. After setting the +default, you can customize further with `sbx policy allow` and +`sbx policy deny` as usual. + +### Default policy + +All outbound HTTP/HTTPS traffic is blocked by default unless an explicit rule +allows it. The **Balanced** policy ships with a baseline allowlist covering AI provider +APIs, package managers, code hosts, container registries, and common cloud +services. Run `sbx policy ls` to see the active rules for your installation. + +Organization admins can modify or remove these defaults when configuring +[organization policies](#organization-policies). + +### Managing local rules + +Use [`sbx policy allow`](/reference/cli/sbx/policy/allow/) and +[`sbx policy deny`](/reference/cli/sbx/policy/deny/) to add network access +rules. Changes take effect immediately and apply to all sandboxes: + +```console +$ sbx policy allow network api.anthropic.com +$ sbx policy deny network ads.example.com +``` + +Specify multiple hosts in one command with a comma-separated list: + +```console +$ sbx policy allow network "api.anthropic.com,*.npmjs.org,*.pypi.org" +``` + +List all active policy rules with `sbx policy ls`: + +```console +$ sbx policy ls +ID TYPE DECISION RESOURCES +a1b2c3d4-e5f6-7890-abcd-ef1234567890 network allow api.anthropic.com, *.npmjs.org +f9e8d7c6-b5a4-3210-fedc-ba0987654321 network deny ads.example.com +``` + +Use `--type network` to show only network policies. + +Remove a policy by resource or by rule ID: + +```console +$ sbx policy rm network --resource ads.example.com +$ sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 +``` + +### Resetting to defaults + +To remove all custom policies and restore the default policy, use +`sbx policy reset`: + +```console +$ sbx policy reset +``` + +This deletes the local policy store and stops the daemon. When the daemon +restarts on the next command, you are prompted to choose a new network policy. +If sandboxes are running, they stop when the daemon shuts down. You are prompted for +confirmation unless you pass `--force`: + +```console +$ sbx policy reset --force +``` + +### Switching to allow-by-default + +If you prefer a permissive policy where all outbound traffic is allowed, add +a wildcard allow rule: + +```console +$ sbx policy allow network "**" +``` + +This lets agents install packages and call any external API without additional +configuration. You can still deny specific hosts with `sbx policy deny`. + +### Org-level rules {tier="Limited Access"} + +Define network allow and deny rules in the Admin Console under +**AI governance > Network access**. Each rule takes a network target (domain, +wildcard, or CIDR range) and an action (allow or deny). You can add multiple +entries at once, one per line. + +Organization-level rules use the same [wildcard syntax](#wildcard-syntax) as +local rules. + +### Wildcard syntax + +Rules support exact domains (`example.com`), wildcard subdomains +(`*.example.com`), and optional port suffixes (`example.com:443`). + +Note that `example.com` doesn't match subdomains, and `*.example.com` doesn't +match the root domain. Specify both to cover both. + +### Common patterns + +Allow access to package managers so agents can install dependencies: + +```console +$ sbx policy allow network "*.npmjs.org,*.pypi.org,files.pythonhosted.org,github.com" +``` + +The **Balanced** policy already includes AI provider APIs, package managers, +code hosts, and container registries. You only need to add allow rules for +additional domains your workflow requires. If you chose **Locked Down**, you +must explicitly allow everything. + +> [!WARNING] +> Allowing broad domains like `github.com` permits access to any content on +> that domain, including user-generated content. Only allow domains you trust +> with your data. + +### Monitoring + +Use `sbx policy log` to see which hosts your sandboxes have contacted: + +```console +$ sbx policy log +Blocked requests: +SANDBOX TYPE HOST PROXY RULE LAST SEEN COUNT +my-sandbox network blocked.example.com transparent policykit 10:15:25 29-Jan 1 + +Allowed requests: +SANDBOX TYPE HOST PROXY RULE LAST SEEN COUNT +my-sandbox network api.anthropic.com forward policykit 10:15:23 29-Jan 42 +my-sandbox network registry.npmjs.org transparent policykit 10:15:20 29-Jan 18 +``` + +The **PROXY** column shows how the request left the sandbox: + +| Value | Description | +| ------------- | --------------------------------------------------------------------------------------------------- | +| `forward` | Routed through the forward proxy. Supports [credential injection](credentials.md). | +| `transparent` | Intercepted by the transparent proxy. Policy is enforced but credential injection is not available. | +| `network` | Non-HTTP traffic (raw TCP, UDP, ICMP). Always blocked. | + +Filter by sandbox name by passing it as an argument: + +```console +$ sbx policy log my-sandbox +``` + +Use `--limit N` to show only the last `N` entries, `--json` for +machine-readable output, or `--type network` to filter by policy type. + +## Filesystem policies + +Filesystem policies control which host paths a sandbox can mount as +workspaces. By default, sandboxes can mount any directory the user has +access to. + +### Org-level restrictions {tier="Limited Access"} + +Admins can restrict which paths are mountable by defining filesystem allow +and deny rules in the Admin Console under **AI governance > Filesystem access**. +Each rule takes a path pattern and an action (allow or deny). + +> [!CAUTION] +> Use `**` (double wildcard) rather than `*` (single wildcard) when writing +> path patterns to match path segments recursively. A single `*` only matches +> within a single path segment. For example, `~/**` matches all paths under the +> user's home directory, whereas `~/*` matches only paths directly under `~`. + +## Precedence + +Within any layer, deny rules beat allow rules — if a domain matches both, +it's blocked regardless of specificity. + +Docker Sandboxes ships with a baseline allowlist (the default policies). Local +`sbx policy` rules add to this baseline. The full evaluation order when +organization policies are enabled: + +1. **Organization policies** (Docker Admin Console) — highest precedence. + Organization admins can modify or replace the default allowlist and define + their own rules. Organization-level denials can't be overridden locally. +2. **Local extensions** — if the admin has enabled the **User defined** + setting, users can add allow rules with `sbx policy allow network`. These + can only expand access within what the organization permits. +3. **Local rules** (`sbx policy`) — lowest precedence. Can't override + organization-level denials. + +The same model applies to filesystem policies: organization-level rules take +precedence over local behavior. + +To unblock a domain, identify where the deny rule comes from. For local rules, +remove it with `sbx policy rm`. For organization-level rules, contact your +organization admin. + +## Troubleshooting + +### Policy changes not taking effect + +If policy changes aren't taking effect, run `sbx policy reset` to wipe the +local policy store and restart the daemon. On next start, you are prompted to +choose a new network policy, and the latest organization policies are pulled if +governance is enabled. + +### Sandbox cannot mount workspace + +If a sandbox fails to mount with a `mount policy denied` error, verify that +the filesystem allow rule uses `**` rather than `*`. A single `*` doesn't +match across directory separators. diff --git a/content/manuals/ai/sandboxes/security/workspace.md b/content/manuals/ai/sandboxes/security/workspace.md new file mode 100644 index 0000000000..cc1db7d200 --- /dev/null +++ b/content/manuals/ai/sandboxes/security/workspace.md @@ -0,0 +1,73 @@ +--- +title: Workspace trust +weight: 40 +description: | + How sandboxed agents interact with your workspace files and what to review + after an agent session. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +Agents running in sandboxes have full access to the workspace directory without +prompting. With the default direct mount, changes the agent makes appear on +your host immediately. Treat sandbox-modified workspace files the same way +you would treat a pull request from an untrusted contributor: review before +you trust them on your host. + +## What the agent can modify + +The agent can create, modify, and delete any file in the workspace. This +includes: + +- Source code files +- Configuration files (`.eslintrc`, `pyproject.toml`, `.env`, etc.) +- Build files (`Makefile`, `package.json`, `Cargo.toml`) +- Git hooks (`.git/hooks/`) +- CI configuration (`.github/workflows/`, `.gitlab-ci.yml`) +- IDE configuration (`.vscode/tasks.json`, `.idea/` run configurations) +- Hidden files and directories +- Shell scripts and executables + +> [!CAUTION] +> Files like Git hooks, CI configuration, IDE task configs, and build scripts +> execute code when triggered by normal development actions such as committing, +> building, or opening the project in an IDE. Review these files after any agent +> session before performing those actions. + +## Branch mode + +The `--branch` flag lets the agent work on a separate branch. This is a +workflow convenience, not a security boundary: the agent still mounts the full +repository. See the [usage guide](../usage.md) for details. + +## Reviewing changes + +After an agent session, review changes before executing any code the agent +touched. + +With the default direct mount, changes are in your working tree: + +```console +$ git diff +``` + +If you used `--branch`, the agent's changes are on a separate branch: + +```console +$ git diff main..my-feature +``` + +Pay particular attention to: + +- **Git hooks** (`.git/hooks/`): run on commit, push, and other Git actions. + These are inside `.git/` and **do not appear in `git diff` output**. Check + them separately with `ls -la .git/hooks/`. +- **CI configuration** (`.github/workflows/`, `.gitlab-ci.yml`): runs on push +- **Build files** (`Makefile`, `package.json` scripts, `Cargo.toml`): run + during build or install steps +- **IDE configuration** (`.vscode/tasks.json`, `.idea/`): can run tasks when + you open the project +- **Executable files and shell scripts**: can run directly + +These files execute code without you explicitly running them. Review them before +committing, building, or opening the project in an IDE. diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md new file mode 100644 index 0000000000..16eef2a8b4 --- /dev/null +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -0,0 +1,137 @@ +--- +title: Troubleshooting +weight: 60 +description: Resolve common issues when using Docker Sandboxes. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +## Resetting sandboxes + +If you hit persistent issues or corrupted state, run +[`sbx reset`](/reference/cli/sbx/reset/) to stop all VMs and delete all sandbox +data. Create fresh sandboxes afterwards. + +## Agent can't install packages or reach an API + +Sandboxes use a [deny-by-default network policy](security/policy.md). +If the agent fails to install packages or call an external API, the target +domain is likely not in the allow list. Check which requests are being blocked: + +```console +$ sbx policy log +``` + +Then allow the domains your workflow needs: + +```console +$ sbx policy allow network "*.npmjs.org,*.pypi.org,files.pythonhosted.org" +``` + +To allow all outbound traffic instead: + +```console +$ sbx policy allow network "**" +``` + +## Docker authentication failure + +If you see a message like `You are not authenticated to Docker`, your login +session has expired. In an interactive terminal, the CLI prompts you to sign in +again. In non-interactive environments such as scripts or CI, run `sbx login` +to re-authenticate. + +## Agent authentication failure + +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 +you haven't set the API key to an invalid value inside the sandbox — the proxy +injects credentials automatically on outbound requests. + +If credentials are configured correctly but API calls still fail, check +`sbx policy log` and look at the **PROXY** column. Requests routed through +the `transparent` proxy don't get credential injection. This can happen when a +client inside the sandbox (such as a process in a Docker container) isn't +configured to use the forward proxy. See +[Monitoring network activity](security/policy.md#monitoring-network-activity) +for details. + +## Docker not available inside the sandbox on Windows + +On Windows, sandboxes use non-docker template variants by default, so `docker` +commands aren't available inside the sandbox. To use Docker inside a sandbox on +Windows, specify a `-docker` template: + +```console +$ sbx run --template docker.io/docker/sandbox-templates:claude-code-docker claude +``` + +The `-docker` variants work on Windows but have slower startup times. See +[Base images](agents/custom-environments.md#base-images) for details and the +full list of templates. + +## Docker build export fails with "lchown: operation not permitted" + +Running `docker build` with the local exporter (`--output=type=local` or `-o +`) inside a sandbox fails because the exporter tries to `lchown` output +files to preserve ownership from the build. Processes inside the sandbox run as +an unprivileged user without `CAP_CHOWN`, so the operation is denied. + +Use the tar exporter and extract the archive instead: + +```console +$ docker build --output type=tar,dest=- . | tar xf - -C ./result +``` + +Extracting the tar archive as the current user avoids the `chown` call. + +## Stale Git worktree after removing a sandbox + +If you used `--branch`, worktree cleanup during `sbx rm` is best-effort. If +it fails, the sandbox is removed but the branch and worktree are left behind. +If `git worktree list` shows a stale worktree in `.sbx/` after removing a +sandbox, clean it up manually: + +```console +$ git worktree remove .sbx/-worktrees/ +$ git branch -D +``` + +## Clock drift after sleep/wake + +If your laptop sleeps and wakes while a sandbox is running, the VM clock can +fall behind the host clock. This causes problems such as: + +- External API calls failing because of timestamp validation. +- Git commits with incorrect timestamps. +- TLS certificate errors due to time mismatches. + +To fix the issue, stop and restart the sandbox: + +```console +$ sbx stop +$ sbx run +``` + +Restarting the sandbox re-syncs the VM clock with the host. + +## Removing all state + +As a last resort, if `sbx reset` doesn't resolve your issue, you can remove the +`sbx` state directory entirely. This deletes all sandbox data, configuration, and +cached images. Stop all running sandboxes first with `sbx reset`. + +macOS: + +```console +$ rm -rf ~/Library/Application\ Support/com.docker.sandboxes/ +``` + +Windows: + +```powershell +> Remove-Item -Recurse -Force "$env:LOCALAPPDATA\DockerSandboxes" +``` diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md new file mode 100644 index 0000000000..6d7fb15655 --- /dev/null +++ b/content/manuals/ai/sandboxes/usage.md @@ -0,0 +1,307 @@ +--- +title: Usage +weight: 20 +description: Common patterns for working with sandboxes. +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +## Working with sandboxes + +The basic workflow is [`run`](/reference/cli/sbx/run/) to start, +[`ls`](/reference/cli/sbx/ls/) to check status, +[`stop`](/reference/cli/sbx/stop/) to pause, and +[`rm`](/reference/cli/sbx/rm/) to clean up: + +```console +$ sbx run claude # start an agent +$ sbx ls # see what's running +$ sbx stop my-sandbox # pause it +$ sbx rm my-sandbox # delete it entirely +``` + +To get a shell inside a running sandbox — useful for inspecting the environment, +checking Docker containers, or manually installing something: + +```console +$ sbx exec -it bash +``` + +If you need a clean slate, remove the sandbox and re-run: + +```console +$ sbx rm my-sandbox +$ sbx run claude +``` + +## Interactive mode + +Running `sbx` with no subcommands opens an interactive terminal dashboard: + +```console +$ sbx +``` + +The dashboard shows all your sandboxes as cards with live status, CPU, and +memory usage. From here you can: + +- **Create** a sandbox (`c`). +- **Start or stop** a sandbox (`s`). +- **Attach** to an agent session (`Enter`), same as `sbx run`. +- **Open a shell** inside the sandbox (`x`), same as `sbx exec`. +- **Remove** a sandbox (`r`). + +The dashboard also includes a network governance panel where you can monitor +outbound connections made by your sandboxes and manage network rules. Use `tab` +to switch between the sandboxes panel and the network panel. + +From the network panel you can browse connection logs, allow or block specific +hosts, and add custom network rules. Press `?` to see all keyboard shortcuts. + +## Git workflow + +When your workspace is a Git repository, the agent edits your working tree +directly by default. Changes appear in your working tree immediately, the same +as working in a normal terminal. + +If you run multiple agents on the same repository at once, use [branch +mode](#branch-mode) to give each agent its own branch and working directory. + +### Direct mode (default) + +The agent edits your working tree directly. Stage, commit, and push as you +normally would. If you run multiple agents on the same repository at the same +time, they may step on each other's changes. See +[branch mode](#branch-mode) for an alternative. + +### Branch mode + +Pass `--branch ` to give the agent its own +[Git worktree](https://git-scm.com/docs/git-worktree) and branch. This +prevents conflicts when multiple agents, or you and an agent, write to the +same files at the same time. You can set `--branch` on `create`, `run`, or +both. + +The CLI creates worktrees under `.sbx/` in your repository root. The +worktree is a separate working directory, so the agent doesn't touch your main +working tree. This means: + +- The worktree branches off your latest commit when you create it. + Uncommitted changes in your working tree are not included (`sbx` warns you + if it detects any). +- Files you add or change in your main working tree won't be visible to the + agent, and vice versa. The two directories are independent. + +#### Starting a branch + +```console +$ sbx run claude --branch my-feature # agent works on the my-feature branch +``` + +Use `--branch auto` to let the CLI generate a branch name for you: + +```console +$ sbx run claude --branch auto +``` + +You can also create the sandbox first and add a branch at run time: + +```console +$ sbx create --name my-sandbox claude . +$ sbx run --branch my-feature my-sandbox +``` + +Or set the branch at create time and reuse it on subsequent runs: + +```console +$ sbx create --name my-sandbox --branch my-feature claude . +$ sbx run my-sandbox # resumes in the my-feature worktree +$ sbx run --branch my-feature my-sandbox # same — reuses the existing worktree +``` + +#### Multiple branches per sandbox + +You can run multiple worktrees in the same sandbox by passing different branch +names: + +```console +$ sbx run --branch feature-a my-sandbox +$ sbx run --branch feature-b my-sandbox +``` + +#### Reviewing and pushing changes + +To review the agent's work, find the worktree with `git worktree list`, then +push or open a PR from there: + +```console +$ git worktree list # find the worktree path +$ cd .sbx/-worktrees/my-feature +$ git log # see what the agent did +$ git push -u origin my-feature +$ gh pr create +``` + +Some agents don't commit automatically and leave changes uncommitted in the +worktree. If that happens, commit from the worktree directory before pushing. + +See [Workspace trust](security/workspace.md) for security considerations when +reviewing agent changes. + +#### Cleanup + +`sbx rm` removes the sandbox and all of its worktrees and branches. + +#### Ignoring the `.sbx/` directory + +Branch mode stores worktrees under `.sbx/` in your repository root. To keep +this directory out of `git status`, add it to your project's `.gitignore`: + +```console +$ echo '.sbx/' >> .gitignore +``` + +Or, to ignore it across all repositories, add `.sbx/` to your global gitignore: + +```console +$ echo '.sbx/' >> "$(git config --global core.excludesFile)" +``` + +> [!TIP] +> If `git config --global core.excludesFile` is empty, set one first: +> `git config --global core.excludesFile ~/.gitignore`. + +You can also create Git worktrees yourself and run an agent directly in one, +but the sandbox won't have access to the `.git` directory in the parent +repository. This means the agent can't commit, push, or use Git. `--branch` +solves this by setting up the worktree so that Git works inside the sandbox. + +## Reconnecting and naming + +Sandboxes persist after the agent exits. Running the same workspace path again +reconnects to the existing sandbox rather than creating a new one: + +```console +$ sbx run claude ~/my-project # creates sandbox +$ sbx run claude ~/my-project # reconnects to same sandbox +``` + +Use `--name` to make this explicit and avoid ambiguity: + +```console +$ sbx run claude --name my-project +``` + +## Creating without attaching + +[`sbx run`](/reference/cli/sbx/run/) creates the sandbox and attaches you to +the agent. To create a sandbox in the background without attaching: + +```console +$ sbx create claude . +``` + +Unlike `run`, `create` requires an explicit workspace path. It uses direct +mode by default, or pass `--branch` for [branch mode](#branch-mode). Attach +later with `sbx run`: + +```console +$ sbx run claude-my-project +``` + +## Multiple workspaces + +You can mount extra directories into a sandbox alongside the main workspace. +The first path is the primary workspace — the agent starts here, and the +sandbox's Git worktree is created from this directory if you use `--branch`. +Extra workspaces are always mounted directly. + +All workspaces appear inside the sandbox at their absolute host paths. Append +`:ro` to mount an extra workspace read-only — useful for reference material or +shared libraries the agent shouldn't modify: + +```console +$ sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro +``` + +Each sandbox is completely isolated, so you can also run separate projects +side-by-side. Remove unused sandboxes when you're done to reclaim disk space: + +```console +$ sbx run claude ~/project-a +$ sbx run claude ~/project-b +$ sbx rm # when finished +``` + +## Installing dependencies and using Docker + +Ask the agent to install what's needed — it has sudo access, and installed +packages persist for the sandbox's lifetime. For teams or repeated setups, +[custom templates](agents/custom-environments.md) let you pre-install tools +into a reusable image. + +Agents can also build Docker images, run containers, and use +[Compose](https://docs.docker.com/compose/). Everything runs inside the sandbox's private Docker +daemon, so containers started by the agent never appear in your host's +`docker ps`. When you remove the sandbox, all images, containers, and volumes +inside it are deleted with it. + +## Accessing services in the sandbox + +Sandboxes are [network-isolated](security/isolation.md) — your browser or local +tools can't reach a server running inside one by default. Use +[`sbx ports`](/reference/cli/sbx/ports/) to forward traffic from your host into +a running sandbox. + +The common case: an agent has started a dev server or API, and you want to open +it in your browser or run tests against it. + +```console +$ sbx ports my-sandbox --publish 8080:3000 # host 8080 → sandbox port 3000 +$ open http://localhost:8080 +``` + +To let the OS pick a free host port instead of choosing one yourself: + +```console +$ sbx ports my-sandbox --publish 3000 # ephemeral host port +$ sbx ports my-sandbox # check which port was assigned +``` + +`sbx ls` shows active port mappings alongside each sandbox, and `sbx ports` +lists them in detail: + +```console +$ sbx ls +SANDBOX AGENT STATUS PORTS WORKSPACE +my-sandbox claude running 127.0.0.1:8080->3000/tcp /home/user/proj +``` + +To stop forwarding a port: + +```console +$ sbx ports my-sandbox --unpublish 8080:3000 +``` + +A few things to keep in mind: + +- **Services must bind to `0.0.0.0`** — a service listening on `127.0.0.1` + inside the sandbox won't be reachable through a published port. Most dev + servers default to `127.0.0.1`, so you'll usually need to pass a flag like + `--host 0.0.0.0` when starting them. +- **Not persistent** — published ports are lost when the sandbox stops or the + daemon restarts. Re-publish after restarting. +- **No create-time flag** — unlike `docker run -p`, there's no `--publish` + option on `sbx run` or `sbx create`. Ports can only be published after the + sandbox is running. +- **Unpublish requires the host port** — `--unpublish 3000` is rejected; you + must use `--unpublish 8080:3000`. Run `sbx ports my-sandbox` first if you + used an ephemeral port and need to find the assigned host port. + +## 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 — only your workspace files +remain on your host. To preserve a configured environment, create a +[custom template](agents/custom-environments.md). diff --git a/content/reference/cli/sbx/_content.gotmpl b/content/reference/cli/sbx/_content.gotmpl new file mode 100644 index 0000000000..b1475f2a05 --- /dev/null +++ b/content/reference/cli/sbx/_content.gotmpl @@ -0,0 +1,48 @@ +{{- /* + Content adapter for sbx CLI reference pages. + + Generates pages from YAML data files in site.Data.sbx_cli (cobra/doc format). + For each YAML file it creates a page at the command path (spaces → slashes). + Commands with child entries in see_also become Hugo sections; others become + regular pages. +*/ -}} + +{{- range $name, $data := site.Data.sbx_cli -}} + {{- if not $data.name -}} + {{- continue -}} + {{- end -}} + + {{- /* Determine if this command has child commands (from see_also) */ -}} + {{- $hasChildren := false -}} + {{- $prefix := printf "%s " $data.name -}} + {{- with $data.see_also -}} + {{- range . -}} + {{- $cmd := index (split . " - ") 0 -}} + {{- if strings.HasPrefix $cmd $prefix -}} + {{- $hasChildren = true -}} + {{- end -}} + {{- end -}} + {{- end -}} + + {{- /* Compute path relative to this adapter (strip "sbx/" prefix) */ -}} + {{- $fullPath := replace $data.name " " "/" -}} + {{- $kind := cond $hasChildren "section" "page" -}} + + {{- if eq $data.name "sbx" -}} + {{- /* Root command is the section index */ -}} + {{- $.AddPage (dict + "path" "." + "title" $data.name + "kind" "section" + "params" (dict "datafile" $name) + ) -}} + {{- else -}} + {{- $relPath := strings.TrimPrefix "sbx/" $fullPath -}} + {{- $.AddPage (dict + "path" $relPath + "title" $data.name + "kind" $kind + "params" (dict "datafile" $name) + ) -}} + {{- end -}} +{{- end -}} diff --git a/data/sbx_cli/sbx.yaml b/data/sbx_cli/sbx.yaml new file mode 100644 index 0000000000..0cdde69210 --- /dev/null +++ b/data/sbx_cli/sbx.yaml @@ -0,0 +1,32 @@ +name: sbx +synopsis: Manage AI coding agent sandboxes. +description: |- + Docker Sandboxes creates isolated sandbox environments for AI agents, powered by Docker. + + Run without a command to launch interactive mode, or pass a command for CLI usage. +usage: sbx +options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging + - name: help + shorthand: h + default_value: "false" + usage: help for sbx +see_also: + - sbx completion - Generate the autocompletion script for the specified shell + - sbx create - Create a sandbox for an agent + - sbx exec - Execute a command inside a sandbox + - sbx login - Sign in to Docker + - sbx logout - Sign out of Docker + - sbx ls - List sandboxes + - sbx policy - Manage sandbox policies + - sbx ports - Manage sandbox port publishing + - sbx reset - Reset all sandboxes and clean up state + - sbx rm - Remove one or more sandboxes + - sbx run - Run an agent in a sandbox + - sbx save - Save a snapshot of the sandbox as a template + - sbx secret - Manage stored secrets + - sbx stop - Stop one or more sandboxes without removing them + - sbx version - Show Docker Sandboxes version information diff --git a/data/sbx_cli/sbx_completion.yaml b/data/sbx_cli/sbx_completion.yaml new file mode 100644 index 0000000000..1416516a62 --- /dev/null +++ b/data/sbx_cli/sbx_completion.yaml @@ -0,0 +1,21 @@ +name: sbx completion +synopsis: Generate the autocompletion script for the specified shell +description: | + Generate the autocompletion script for sbx for the specified shell. + See each sub-command's help for details on how to use the generated script. +options: + - name: help + shorthand: h + default_value: "false" + usage: help for completion +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. + - sbx completion bash - Generate the autocompletion script for bash + - sbx completion fish - Generate the autocompletion script for fish + - sbx completion powershell - Generate the autocompletion script for powershell + - sbx completion zsh - Generate the autocompletion script for zsh diff --git a/data/sbx_cli/sbx_completion_bash.yaml b/data/sbx_cli/sbx_completion_bash.yaml new file mode 100644 index 0000000000..4e06d587fb --- /dev/null +++ b/data/sbx_cli/sbx_completion_bash.yaml @@ -0,0 +1,39 @@ +name: sbx completion bash +synopsis: Generate the autocompletion script for bash +description: | + Generate the autocompletion script for the bash shell. + + This script depends on the 'bash-completion' package. + If it is not installed already, you can install it via your OS's package manager. + + To load completions in your current shell session: + + source <(sbx completion bash) + + To load completions for every new session, execute once: + + #### Linux: + + sbx completion bash > /etc/bash_completion.d/sbx + + #### macOS: + + sbx completion bash > $(brew --prefix)/etc/bash_completion.d/sbx + + You will need to start a new shell for this setup to take effect. +usage: sbx completion bash +options: + - name: help + shorthand: h + default_value: "false" + usage: help for bash + - name: no-descriptions + default_value: "false" + usage: disable completion descriptions +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx completion - Generate the autocompletion script for the specified shell diff --git a/data/sbx_cli/sbx_completion_fish.yaml b/data/sbx_cli/sbx_completion_fish.yaml new file mode 100644 index 0000000000..2d38fe4b2d --- /dev/null +++ b/data/sbx_cli/sbx_completion_fish.yaml @@ -0,0 +1,30 @@ +name: sbx completion fish +synopsis: Generate the autocompletion script for fish +description: | + Generate the autocompletion script for the fish shell. + + To load completions in your current shell session: + + sbx completion fish | source + + To load completions for every new session, execute once: + + sbx completion fish > ~/.config/fish/completions/sbx.fish + + You will need to start a new shell for this setup to take effect. +usage: sbx completion fish [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for fish + - name: no-descriptions + default_value: "false" + usage: disable completion descriptions +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx completion - Generate the autocompletion script for the specified shell diff --git a/data/sbx_cli/sbx_completion_powershell.yaml b/data/sbx_cli/sbx_completion_powershell.yaml new file mode 100644 index 0000000000..6a442b5d99 --- /dev/null +++ b/data/sbx_cli/sbx_completion_powershell.yaml @@ -0,0 +1,27 @@ +name: sbx completion powershell +synopsis: Generate the autocompletion script for powershell +description: | + Generate the autocompletion script for powershell. + + To load completions in your current shell session: + + sbx completion powershell | Out-String | Invoke-Expression + + To load completions for every new session, add the output of the above command + to your powershell profile. +usage: sbx completion powershell [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for powershell + - name: no-descriptions + default_value: "false" + usage: disable completion descriptions +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx completion - Generate the autocompletion script for the specified shell diff --git a/data/sbx_cli/sbx_completion_zsh.yaml b/data/sbx_cli/sbx_completion_zsh.yaml new file mode 100644 index 0000000000..2ccf93f0dd --- /dev/null +++ b/data/sbx_cli/sbx_completion_zsh.yaml @@ -0,0 +1,41 @@ +name: sbx completion zsh +synopsis: Generate the autocompletion script for zsh +description: | + Generate the autocompletion script for the zsh shell. + + If shell completion is not already enabled in your environment you will need + to enable it. You can execute the following once: + + echo "autoload -U compinit; compinit" >> ~/.zshrc + + To load completions in your current shell session: + + source <(sbx completion zsh) + + To load completions for every new session, execute once: + + #### Linux: + + sbx completion zsh > "${fpath[1]}/_sbx" + + #### macOS: + + sbx completion zsh > $(brew --prefix)/share/zsh/site-functions/_sbx + + You will need to start a new shell for this setup to take effect. +usage: sbx completion zsh [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for zsh + - name: no-descriptions + default_value: "false" + usage: disable completion descriptions +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx completion - Generate the autocompletion script for the specified shell diff --git a/data/sbx_cli/sbx_create.yaml b/data/sbx_cli/sbx_create.yaml new file mode 100644 index 0000000000..99ce7bd634 --- /dev/null +++ b/data/sbx_cli/sbx_create.yaml @@ -0,0 +1,56 @@ +name: sbx create +synopsis: Create a sandbox for an agent +description: |- + Create a sandbox with access to a host workspace for an agent. + + Use "sbx run SANDBOX" to attach to the agent after creation. +usage: sbx create [flags] AGENT PATH [PATH...] +options: + - name: branch + usage: Create a Git worktree on the given branch + - name: help + shorthand: h + default_value: "false" + usage: help for create + - name: memory + shorthand: m + usage: | + Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + - name: name + usage: | + Name for the sandbox (default: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + - name: quiet + shorthand: q + default_value: "false" + usage: Suppress verbose output + - name: template + shorthand: t + usage: | + Container image to use for the sandbox (default: agent-specific image) +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Create a sandbox for Claude in the current directory + sbx create claude . + + # Create a sandbox with a custom name + sbx create --name my-project claude /path/to/project + + # Create with additional read-only workspaces + sbx create claude . /path/to/docs:ro + + # Create with a Git worktree for isolated changes + sbx create --branch=feature/login claude . +see_also: + - sbx - Manage AI coding agent sandboxes. + - sbx create claude - Create a sandbox for claude + - sbx create codex - Create a sandbox for codex + - sbx create copilot - Create a sandbox for copilot + - sbx create docker-agent - Create a sandbox for docker-agent + - sbx create gemini - Create a sandbox for gemini + - sbx create kiro - Create a sandbox for kiro + - sbx create opencode - Create a sandbox for opencode + - sbx create shell - Create a sandbox for shell diff --git a/data/sbx_cli/sbx_create_claude.yaml b/data/sbx_cli/sbx_create_claude.yaml new file mode 100644 index 0000000000..455e1ffda3 --- /dev/null +++ b/data/sbx_cli/sbx_create_claude.yaml @@ -0,0 +1,49 @@ +name: sbx create claude +synopsis: Create a sandbox for claude +description: |- + Create a sandbox with access to a host workspace for claude. + + The workspace path is required and will be mounted inside the sandbox at the + same path as on the host. Additional workspaces can be provided as extra + arguments. Append ":ro" to mount them read-only. + + Use "sbx run SANDBOX" to attach to the agent after creation. +usage: sbx create claude PATH [PATH...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for claude +inherited_options: + - name: branch + usage: Create a Git worktree on the given branch + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging + - name: memory + shorthand: m + usage: | + Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + - name: name + usage: | + Name for the sandbox (default: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + - name: quiet + shorthand: q + default_value: "false" + usage: Suppress verbose output + - name: template + shorthand: t + usage: | + Container image to use for the sandbox (default: agent-specific image) +example: |4- + # Create in the current directory + sbx create claude . + + # Create with a specific path + sbx create claude /path/to/project + + # Create with additional read-only workspaces + sbx create claude . /path/to/docs:ro +see_also: + - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_codex.yaml b/data/sbx_cli/sbx_create_codex.yaml new file mode 100644 index 0000000000..e99f6af82b --- /dev/null +++ b/data/sbx_cli/sbx_create_codex.yaml @@ -0,0 +1,49 @@ +name: sbx create codex +synopsis: Create a sandbox for codex +description: |- + Create a sandbox with access to a host workspace for codex. + + The workspace path is required and will be mounted inside the sandbox at the + same path as on the host. Additional workspaces can be provided as extra + arguments. Append ":ro" to mount them read-only. + + Use "sbx run SANDBOX" to attach to the agent after creation. +usage: sbx create codex PATH [PATH...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for codex +inherited_options: + - name: branch + usage: Create a Git worktree on the given branch + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging + - name: memory + shorthand: m + usage: | + Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + - name: name + usage: | + Name for the sandbox (default: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + - name: quiet + shorthand: q + default_value: "false" + usage: Suppress verbose output + - name: template + shorthand: t + usage: | + Container image to use for the sandbox (default: agent-specific image) +example: |4- + # Create in the current directory + sbx create codex . + + # Create with a specific path + sbx create codex /path/to/project + + # Create with additional read-only workspaces + sbx create codex . /path/to/docs:ro +see_also: + - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_copilot.yaml b/data/sbx_cli/sbx_create_copilot.yaml new file mode 100644 index 0000000000..06a2c48032 --- /dev/null +++ b/data/sbx_cli/sbx_create_copilot.yaml @@ -0,0 +1,49 @@ +name: sbx create copilot +synopsis: Create a sandbox for copilot +description: |- + Create a sandbox with access to a host workspace for copilot. + + The workspace path is required and will be mounted inside the sandbox at the + same path as on the host. Additional workspaces can be provided as extra + arguments. Append ":ro" to mount them read-only. + + Use "sbx run SANDBOX" to attach to the agent after creation. +usage: sbx create copilot PATH [PATH...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for copilot +inherited_options: + - name: branch + usage: Create a Git worktree on the given branch + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging + - name: memory + shorthand: m + usage: | + Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + - name: name + usage: | + Name for the sandbox (default: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + - name: quiet + shorthand: q + default_value: "false" + usage: Suppress verbose output + - name: template + shorthand: t + usage: | + Container image to use for the sandbox (default: agent-specific image) +example: |4- + # Create in the current directory + sbx create copilot . + + # Create with a specific path + sbx create copilot /path/to/project + + # Create with additional read-only workspaces + sbx create copilot . /path/to/docs:ro +see_also: + - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_docker-agent.yaml b/data/sbx_cli/sbx_create_docker-agent.yaml new file mode 100644 index 0000000000..d7824dc954 --- /dev/null +++ b/data/sbx_cli/sbx_create_docker-agent.yaml @@ -0,0 +1,49 @@ +name: sbx create docker-agent +synopsis: Create a sandbox for docker-agent +description: |- + Create a sandbox with access to a host workspace for docker-agent. + + The workspace path is required and will be mounted inside the sandbox at the + same path as on the host. Additional workspaces can be provided as extra + arguments. Append ":ro" to mount them read-only. + + Use "sbx run SANDBOX" to attach to the agent after creation. +usage: sbx create docker-agent PATH [PATH...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for docker-agent +inherited_options: + - name: branch + usage: Create a Git worktree on the given branch + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging + - name: memory + shorthand: m + usage: | + Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + - name: name + usage: | + Name for the sandbox (default: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + - name: quiet + shorthand: q + default_value: "false" + usage: Suppress verbose output + - name: template + shorthand: t + usage: | + Container image to use for the sandbox (default: agent-specific image) +example: |4- + # Create in the current directory + sbx create docker-agent . + + # Create with a specific path + sbx create docker-agent /path/to/project + + # Create with additional read-only workspaces + sbx create docker-agent . /path/to/docs:ro +see_also: + - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_gemini.yaml b/data/sbx_cli/sbx_create_gemini.yaml new file mode 100644 index 0000000000..f74247b3f8 --- /dev/null +++ b/data/sbx_cli/sbx_create_gemini.yaml @@ -0,0 +1,49 @@ +name: sbx create gemini +synopsis: Create a sandbox for gemini +description: |- + Create a sandbox with access to a host workspace for gemini. + + The workspace path is required and will be mounted inside the sandbox at the + same path as on the host. Additional workspaces can be provided as extra + arguments. Append ":ro" to mount them read-only. + + Use "sbx run SANDBOX" to attach to the agent after creation. +usage: sbx create gemini PATH [PATH...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for gemini +inherited_options: + - name: branch + usage: Create a Git worktree on the given branch + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging + - name: memory + shorthand: m + usage: | + Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + - name: name + usage: | + Name for the sandbox (default: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + - name: quiet + shorthand: q + default_value: "false" + usage: Suppress verbose output + - name: template + shorthand: t + usage: | + Container image to use for the sandbox (default: agent-specific image) +example: |4- + # Create in the current directory + sbx create gemini . + + # Create with a specific path + sbx create gemini /path/to/project + + # Create with additional read-only workspaces + sbx create gemini . /path/to/docs:ro +see_also: + - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_kiro.yaml b/data/sbx_cli/sbx_create_kiro.yaml new file mode 100644 index 0000000000..766a5cca8f --- /dev/null +++ b/data/sbx_cli/sbx_create_kiro.yaml @@ -0,0 +1,49 @@ +name: sbx create kiro +synopsis: Create a sandbox for kiro +description: |- + Create a sandbox with access to a host workspace for kiro. + + The workspace path is required and will be mounted inside the sandbox at the + same path as on the host. Additional workspaces can be provided as extra + arguments. Append ":ro" to mount them read-only. + + Use "sbx run SANDBOX" to attach to the agent after creation. +usage: sbx create kiro PATH [PATH...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for kiro +inherited_options: + - name: branch + usage: Create a Git worktree on the given branch + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging + - name: memory + shorthand: m + usage: | + Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + - name: name + usage: | + Name for the sandbox (default: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + - name: quiet + shorthand: q + default_value: "false" + usage: Suppress verbose output + - name: template + shorthand: t + usage: | + Container image to use for the sandbox (default: agent-specific image) +example: |4- + # Create in the current directory + sbx create kiro . + + # Create with a specific path + sbx create kiro /path/to/project + + # Create with additional read-only workspaces + sbx create kiro . /path/to/docs:ro +see_also: + - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_opencode.yaml b/data/sbx_cli/sbx_create_opencode.yaml new file mode 100644 index 0000000000..ea45254945 --- /dev/null +++ b/data/sbx_cli/sbx_create_opencode.yaml @@ -0,0 +1,49 @@ +name: sbx create opencode +synopsis: Create a sandbox for opencode +description: |- + Create a sandbox with access to a host workspace for opencode. + + The workspace path is required and will be mounted inside the sandbox at the + same path as on the host. Additional workspaces can be provided as extra + arguments. Append ":ro" to mount them read-only. + + Use "sbx run SANDBOX" to attach to the agent after creation. +usage: sbx create opencode PATH [PATH...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for opencode +inherited_options: + - name: branch + usage: Create a Git worktree on the given branch + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging + - name: memory + shorthand: m + usage: | + Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + - name: name + usage: | + Name for the sandbox (default: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + - name: quiet + shorthand: q + default_value: "false" + usage: Suppress verbose output + - name: template + shorthand: t + usage: | + Container image to use for the sandbox (default: agent-specific image) +example: |4- + # Create in the current directory + sbx create opencode . + + # Create with a specific path + sbx create opencode /path/to/project + + # Create with additional read-only workspaces + sbx create opencode . /path/to/docs:ro +see_also: + - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_shell.yaml b/data/sbx_cli/sbx_create_shell.yaml new file mode 100644 index 0000000000..c591992fdd --- /dev/null +++ b/data/sbx_cli/sbx_create_shell.yaml @@ -0,0 +1,49 @@ +name: sbx create shell +synopsis: Create a sandbox for shell +description: |- + Create a sandbox with access to a host workspace for shell. + + The workspace path is required and will be mounted inside the sandbox at the + same path as on the host. Additional workspaces can be provided as extra + arguments. Append ":ro" to mount them read-only. + + Use "sbx run SANDBOX" to attach to the agent after creation. +usage: sbx create shell PATH [PATH...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for shell +inherited_options: + - name: branch + usage: Create a Git worktree on the given branch + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging + - name: memory + shorthand: m + usage: | + Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + - name: name + usage: | + Name for the sandbox (default: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + - name: quiet + shorthand: q + default_value: "false" + usage: Suppress verbose output + - name: template + shorthand: t + usage: | + Container image to use for the sandbox (default: agent-specific image) +example: |4- + # Create in the current directory + sbx create shell . + + # Create with a specific path + sbx create shell /path/to/project + + # Create with additional read-only workspaces + sbx create shell . /path/to/docs:ro +see_also: + - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_exec.yaml b/data/sbx_cli/sbx_exec.yaml new file mode 100644 index 0000000000..d060aad82f --- /dev/null +++ b/data/sbx_cli/sbx_exec.yaml @@ -0,0 +1,58 @@ +name: sbx exec +synopsis: Execute a command inside a sandbox +description: |- + Execute a command in a sandbox. If the sandbox is stopped, it is started first. + + Flags match the behavior of "docker exec". +usage: sbx exec [flags] SANDBOX COMMAND [ARG...] +options: + - name: detach + shorthand: d + default_value: "false" + usage: 'Detached mode: run command in the background' + - name: detach-keys + usage: Override the key sequence for detaching a container + - name: env + shorthand: e + default_value: '[]' + usage: Set environment variables + - name: env-file + default_value: '[]' + usage: Read in a file of environment variables + - name: help + shorthand: h + default_value: "false" + usage: help for exec + - name: interactive + shorthand: i + default_value: "false" + usage: Keep STDIN open even if not attached + - name: privileged + default_value: "false" + usage: Give extended privileges to the command + - name: tty + shorthand: t + default_value: "false" + usage: Allocate a pseudo-TTY + - name: user + shorthand: u + usage: 'Username or UID (format: [:])' + - name: workdir + shorthand: w + usage: Working directory inside the container +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Open a shell inside a sandbox + sbx exec -it my-sandbox bash + + # Run a command in the background + sbx exec -d my-sandbox npm start + + # Run as root + sbx exec -u root my-sandbox apt-get update +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_login.yaml b/data/sbx_cli/sbx_login.yaml new file mode 100644 index 0000000000..6635623a85 --- /dev/null +++ b/data/sbx_cli/sbx_login.yaml @@ -0,0 +1,15 @@ +name: sbx login +synopsis: Sign in to Docker +usage: sbx login [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for login +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_logout.yaml b/data/sbx_cli/sbx_logout.yaml new file mode 100644 index 0000000000..7d030e1b1c --- /dev/null +++ b/data/sbx_cli/sbx_logout.yaml @@ -0,0 +1,15 @@ +name: sbx logout +synopsis: Sign out of Docker +usage: sbx logout [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for logout +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_ls.yaml b/data/sbx_cli/sbx_ls.yaml new file mode 100644 index 0000000000..51f664b274 --- /dev/null +++ b/data/sbx_cli/sbx_ls.yaml @@ -0,0 +1,24 @@ +name: sbx ls +synopsis: List sandboxes +description: | + List all sandboxes with their agent, status, published ports, and workspace. +usage: sbx ls [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for ls + - name: json + default_value: "false" + usage: Output in JSON format + - name: quiet + shorthand: q + default_value: "false" + usage: Only display sandbox names +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_policy.yaml b/data/sbx_cli/sbx_policy.yaml new file mode 100644 index 0000000000..693817fc2e --- /dev/null +++ b/data/sbx_cli/sbx_policy.yaml @@ -0,0 +1,28 @@ +name: sbx policy +synopsis: Manage sandbox policies +description: |- + Manage persistent access policies for sandboxes. + + Policies are rules stored locally that control what sandboxes can access. + They apply globally across all sandboxes and persist across restarts. + Use subcommands to allow, deny, list, or remove policies. +usage: sbx policy COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for policy +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. + - sbx policy allow - Add an allow policy for sandboxes + - sbx policy deny - Add a deny policy for sandboxes + - sbx policy log - Show sandbox policy logs + - sbx policy ls - List sandbox policies + - sbx policy reset - Reset policies to defaults + - sbx policy rm - Remove a policy + - sbx policy set-default - Set the default network policy diff --git a/data/sbx_cli/sbx_policy_allow.yaml b/data/sbx_cli/sbx_policy_allow.yaml new file mode 100644 index 0000000000..c9f2dfa017 --- /dev/null +++ b/data/sbx_cli/sbx_policy_allow.yaml @@ -0,0 +1,21 @@ +name: sbx policy allow +synopsis: Add an allow policy for sandboxes +description: |- + Add a policy that permits sandboxes to access specified resources. + + Allowed resources are accessible to all sandboxes. If a resource matches both + an allow and a deny rule, the deny rule takes precedence. +usage: sbx policy allow COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for allow +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx policy - Manage sandbox policies + - sbx policy allow network - Allow network access to specified hosts diff --git a/data/sbx_cli/sbx_policy_allow_network.yaml b/data/sbx_cli/sbx_policy_allow_network.yaml new file mode 100644 index 0000000000..6ec52fe692 --- /dev/null +++ b/data/sbx_cli/sbx_policy_allow_network.yaml @@ -0,0 +1,33 @@ +name: sbx policy allow network +synopsis: Allow network access to specified hosts +description: |- + Allow sandbox network access to the specified hosts. + + RESOURCES is a comma-separated list of hostnames, domains, or IP addresses. + Supports exact domains (example.com), wildcard subdomains (*.example.com), + and optional port suffixes (example.com:443). Use "**" to allow all hosts. +usage: sbx policy allow network RESOURCES [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for network +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Allow access to a single host + sbx policy allow network api.example.com + + # Allow access to multiple hosts + sbx policy allow network "api.example.com,cdn.example.com" + + # Allow all subdomains of a host + sbx policy allow network "*.npmjs.org" + + # Allow all outbound traffic + sbx policy allow network "**" +see_also: + - sbx policy allow - Add an allow policy for sandboxes diff --git a/data/sbx_cli/sbx_policy_deny.yaml b/data/sbx_cli/sbx_policy_deny.yaml new file mode 100644 index 0000000000..885ec0e68c --- /dev/null +++ b/data/sbx_cli/sbx_policy_deny.yaml @@ -0,0 +1,21 @@ +name: sbx policy deny +synopsis: Add a deny policy for sandboxes +description: |- + Add a policy that blocks sandboxes from accessing specified resources. + + Deny rules always take precedence over allow rules. If a resource matches + both an allow and a deny rule, the request is blocked. +usage: sbx policy deny COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for deny +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx policy - Manage sandbox policies + - sbx policy deny network - Deny network access to specified hosts diff --git a/data/sbx_cli/sbx_policy_deny_network.yaml b/data/sbx_cli/sbx_policy_deny_network.yaml new file mode 100644 index 0000000000..b26ceffba3 --- /dev/null +++ b/data/sbx_cli/sbx_policy_deny_network.yaml @@ -0,0 +1,26 @@ +name: sbx policy deny network +synopsis: Deny network access to specified hosts +description: |- + Block sandbox network access to the specified hosts. + + RESOURCES is a comma-separated list of hostnames, domains, or IP addresses. + Deny rules always take precedence over allow rules. +usage: sbx policy deny network RESOURCES [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for network +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Block access to a host + sbx policy deny network ads.example.com + + # Block all outbound traffic + sbx policy deny network "**" +see_also: + - sbx policy deny - Add a deny policy for sandboxes diff --git a/data/sbx_cli/sbx_policy_log.yaml b/data/sbx_cli/sbx_policy_log.yaml new file mode 100644 index 0000000000..34c68a60e9 --- /dev/null +++ b/data/sbx_cli/sbx_policy_log.yaml @@ -0,0 +1,46 @@ +name: sbx policy log +synopsis: Show sandbox policy logs +description: |- + Show policy logs for all sandboxes, or filter by a specific sandbox name. + + Displays which hosts were allowed or blocked by the proxy, along with the + matching rule, proxy type, and request count. Useful for debugging connectivity + issues or auditing network activity. +usage: sbx policy log [SANDBOX] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for log + - name: json + default_value: "false" + usage: Output in JSON format + - name: limit + default_value: "0" + usage: Maximum number of log entries to show + - name: quiet + shorthand: q + default_value: "false" + usage: Only display log entries + - name: type + default_value: all + usage: 'Filter logs by type: "all" or "network" (default "all")' +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Show all policy logs + sbx policy log + + # Show logs for a specific sandbox + sbx policy log my-sandbox + + # Output in JSON format + sbx policy log --json + + # Show the last 20 entries + sbx policy log --limit 20 +see_also: + - sbx policy - Manage sandbox policies diff --git a/data/sbx_cli/sbx_policy_ls.yaml b/data/sbx_cli/sbx_policy_ls.yaml new file mode 100644 index 0000000000..87493267f7 --- /dev/null +++ b/data/sbx_cli/sbx_policy_ls.yaml @@ -0,0 +1,29 @@ +name: sbx policy ls +synopsis: List sandbox policies +description: |- + List all active policies. + + Displays the policy name (or ID if no name is set), type, decision + (allow/deny), and the associated resources for each rule. +usage: sbx policy ls [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for ls + - name: type + default_value: all + usage: 'Filter policies by type: "all" or "network" (default "all")' +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # List all policies + sbx policy ls + + # List only network policies + sbx policy ls --type network +see_also: + - sbx policy - Manage sandbox policies diff --git a/data/sbx_cli/sbx_policy_reset.yaml b/data/sbx_cli/sbx_policy_reset.yaml new file mode 100644 index 0000000000..7c4c1ec80b --- /dev/null +++ b/data/sbx_cli/sbx_policy_reset.yaml @@ -0,0 +1,33 @@ +name: sbx policy reset +synopsis: Reset policies to defaults +description: |- + Remove all custom policies and restart the daemon to restore defaults. + + This deletes the local policy store and stops the daemon. When the daemon + restarts (automatically on next command), the default policy is installed. + + If sandboxes are currently running, they will be stopped when the daemon + shuts down. You will be prompted for confirmation unless --force is used. +usage: sbx policy reset [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: Skip confirmation prompt + - name: help + shorthand: h + default_value: "false" + usage: help for reset +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Reset policies (prompts if sandboxes are running) + sbx policy reset + + # Reset policies without confirmation + sbx policy reset --force +see_also: + - sbx policy - Manage sandbox policies diff --git a/data/sbx_cli/sbx_policy_rm.yaml b/data/sbx_cli/sbx_policy_rm.yaml new file mode 100644 index 0000000000..0d71eaf6ee --- /dev/null +++ b/data/sbx_cli/sbx_policy_rm.yaml @@ -0,0 +1,17 @@ +name: sbx policy rm +synopsis: Remove a policy +description: Remove a previously added allow or deny policy. +usage: sbx policy rm COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for rm +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx policy - Manage sandbox policies + - sbx policy rm network - Remove a network policy diff --git a/data/sbx_cli/sbx_policy_rm_network.yaml b/data/sbx_cli/sbx_policy_rm_network.yaml new file mode 100644 index 0000000000..7c154bf058 --- /dev/null +++ b/data/sbx_cli/sbx_policy_rm_network.yaml @@ -0,0 +1,32 @@ +name: sbx policy rm network +synopsis: Remove a network policy +description: |- + Remove a network policy by rule ID, resource, or both. + + Use "sbx policy ls" to see active policies and their IDs/resources. +usage: sbx policy rm network [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for network + - name: id + usage: Remove by rule ID + - name: resource + usage: Remove by resource value(s), comma-separated +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Remove a rule by resource + sbx policy rm network --resource api.example.com + + # Remove a rule by ID + sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 + + # Remove by ID and resource using one filter + sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 --resource "api.example.com,cdn.example.com" +see_also: + - sbx policy rm - Remove a policy diff --git a/data/sbx_cli/sbx_policy_set-default.yaml b/data/sbx_cli/sbx_policy_set-default.yaml new file mode 100644 index 0000000000..1fce7a945e --- /dev/null +++ b/data/sbx_cli/sbx_policy_set-default.yaml @@ -0,0 +1,38 @@ +name: sbx policy set-default +synopsis: Set the default network policy +description: |- + Set the default network policy for all sandboxes. + + This must be run before adding custom allow/deny rules or starting a sandbox + for the first time. The default policy determines the baseline network access. + + Available policies: + allow-all All outbound network traffic is allowed + balanced Common dev traffic allowed (AI services, package registries, etc.) + deny-all All outbound network traffic is blocked + + After setting defaults, use "sbx policy allow/deny" to add custom rules. + Use "sbx policy reset" to clear all policies and start over. +usage: sbx policy set-default [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for set-default +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Set balanced defaults (recommended) + sbx policy set-default balanced + + # Allow all traffic + sbx policy set-default allow-all + + # Block everything, then allow specific sites + sbx policy set-default deny-all + sbx policy allow network api.example.com:443 +see_also: + - sbx policy - Manage sandbox policies diff --git a/data/sbx_cli/sbx_ports.yaml b/data/sbx_cli/sbx_ports.yaml new file mode 100644 index 0000000000..14d586c116 --- /dev/null +++ b/data/sbx_cli/sbx_ports.yaml @@ -0,0 +1,48 @@ +name: sbx ports +synopsis: Manage sandbox port publishing +description: |- + Manage sandbox port publishing. + + List, publish, or unpublish ports for a running sandbox. Without --publish or + --unpublish flags, lists all published ports. + + Port spec format: [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + If HOST_PORT is omitted, an ephemeral port is allocated automatically. + HOST_IP defaults to 127.0.0.1, PROTOCOL defaults to tcp. + Supported protocols: tcp, tcp4, tcp6, udp, udp4, udp6. +usage: sbx ports SANDBOX [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for ports + - name: json + default_value: "false" + usage: Output in JSON format (for port listing) + - name: publish + default_value: '[]' + usage: | + Publish a port (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + - name: unpublish + default_value: '[]' + usage: | + Unpublish a port (can be repeated): [HOST_IP:]HOST_PORT:SANDBOX_PORT[/PROTOCOL] +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # List published ports + sbx ports my-sandbox + + # Publish sandbox port 8080 to an ephemeral host port + sbx ports my-sandbox --publish 8080 + + # Publish with a specific host port + sbx ports my-sandbox --publish 3000:8080 + + # Unpublish a port + sbx ports my-sandbox --unpublish 3000:8080 +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_reset.yaml b/data/sbx_cli/sbx_reset.yaml new file mode 100644 index 0000000000..90f3cf4938 --- /dev/null +++ b/data/sbx_cli/sbx_reset.yaml @@ -0,0 +1,44 @@ +name: sbx reset +synopsis: Reset all sandboxes and clean up state +description: |- + Reset Docker Sandboxes to a freshly-installed state. + + This command will: + - Stop all running sandboxes gracefully (30s timeout) + - Clear image cache + - Clear all internal registries + - Delete all sandbox state + - Remove all policies + - Delete all stored secrets + - Sign out of Docker Sandboxes + - Stop the daemon + - Remove all state, cache, and config directories + + WARNING: This is destructive and cannot be undone. + Running agents will be terminated and their work lost. + Cached images will be deleted and recreated on next use. + Stored secrets will need to be re-entered. + + Use --preserve-secrets to keep stored secrets. + By default, you will be prompted to confirm (y/N). + Use --force to skip the confirmation prompt. +usage: sbx reset [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: Skip confirmation prompt + - name: help + shorthand: h + default_value: "false" + usage: help for reset + - name: preserve-secrets + default_value: "false" + usage: Keep stored secrets +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_rm.yaml b/data/sbx_cli/sbx_rm.yaml new file mode 100644 index 0000000000..4e391e73ba --- /dev/null +++ b/data/sbx_cli/sbx_rm.yaml @@ -0,0 +1,30 @@ +name: sbx rm +synopsis: Remove one or more sandboxes +description: |- + Remove one or more sandboxes and all associated resources. + + Stops running sandboxes, removes their containers, cleans up any Git + worktrees, and deletes sandbox state. This action cannot be undone. + + Use --all to remove every sandbox (requires confirmation). + Use --force to skip confirmation prompts (for non-interactive scripts). +usage: sbx rm [SANDBOX...] [flags] +options: + - name: all + default_value: "false" + usage: Remove all sandboxes + - name: force + shorthand: f + default_value: "false" + usage: Skip confirmation prompts + - name: help + shorthand: h + default_value: "false" + usage: help for rm +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_run.yaml b/data/sbx_cli/sbx_run.yaml new file mode 100644 index 0000000000..e9dfb8a6f8 --- /dev/null +++ b/data/sbx_cli/sbx_run.yaml @@ -0,0 +1,49 @@ +name: sbx run +synopsis: Run an agent in a sandbox +description: |- + Run an agent in a sandbox, creating the sandbox if it does not already exist. + + Pass agent arguments after the "--" separator. Additional workspaces can be + provided as extra arguments. Append ":ro" to mount them read-only. + + To create a sandbox without attaching, use "sbx create" instead. + + Available agents: claude, codex, copilot, docker-agent, gemini, kiro, opencode, shell +usage: sbx run [flags] SANDBOX | AGENT [PATH...] [-- AGENT_ARGS...] +options: + - name: branch + usage: | + Create a Git worktree on the given branch (use --branch auto to auto-generate) + - name: help + shorthand: h + default_value: "false" + usage: help for run + - name: memory + shorthand: m + usage: | + Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + - name: name + usage: 'Name for the sandbox (default: -)' + - name: template + shorthand: t + usage: | + Container image to use for the sandbox (default: agent-specific image) +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Create and run a sandbox with claude in current directory + sbx run claude + + # Create and run with additional workspaces (read-only) + sbx run claude . /path/to/docs:ro + + # Run an existing sandbox + sbx run existing-sandbox + + # Run a sandbox with agent arguments + sbx run claude -- --continue +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_save.yaml b/data/sbx_cli/sbx_save.yaml new file mode 100644 index 0000000000..3239e15ef8 --- /dev/null +++ b/data/sbx_cli/sbx_save.yaml @@ -0,0 +1,30 @@ +name: sbx save +synopsis: Save a snapshot of the sandbox as a template +description: |- + Save a snapshot of the sandbox as a template. + + By default, the image is loaded into the host's Docker daemon (requires Docker to be running). + Use --output to save the image to a tar file instead. +usage: sbx save SANDBOX TAG [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for save + - name: output + shorthand: o + usage: | + Save image to specified tar file instead of loading into host Docker +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Load into host Docker (requires host Docker running) + sbx save my-sandbox myimage:v1.0 + + # Save to file (works without host Docker) + sbx save my-sandbox myimage:v1.0 --output /tmp/myimage.tar +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_secret.yaml b/data/sbx_cli/sbx_secret.yaml new file mode 100644 index 0000000000..55b80ff61d --- /dev/null +++ b/data/sbx_cli/sbx_secret.yaml @@ -0,0 +1,27 @@ +name: sbx secret +synopsis: Manage stored secrets +description: |- + Manage stored secrets for sandbox environments. + + Secrets are stored per service name (e.g., "github", "anthropic", "openai"). + When a sandbox starts, the proxy uses stored secrets to authenticate API + requests on behalf of the agent. The secret is never exposed directly to the + agent. + + Secrets can be scoped globally (shared across all sandboxes) or to a + specific sandbox. +options: + - name: help + shorthand: h + default_value: "false" + usage: help for secret +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. + - sbx secret ls - List stored secrets + - sbx secret rm - Remove a secret + - sbx secret set - Create or update a secret diff --git a/data/sbx_cli/sbx_secret_ls.yaml b/data/sbx_cli/sbx_secret_ls.yaml new file mode 100644 index 0000000000..4105985920 --- /dev/null +++ b/data/sbx_cli/sbx_secret_ls.yaml @@ -0,0 +1,33 @@ +name: sbx secret ls +synopsis: List stored secrets +usage: sbx secret ls [sandbox] [OPTIONS] [flags] +options: + - name: global + shorthand: g + default_value: "false" + usage: Only list global secrets + - name: help + shorthand: h + default_value: "false" + usage: help for ls + - name: service + usage: Filter by secret service name +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # List all secrets + sbx secret ls + + # List only global secrets + sbx secret ls -g + + # List secrets for a specific sandbox + sbx secret ls my-sandbox + + # Filter by service + sbx secret ls --service github +see_also: + - sbx secret - Manage stored secrets diff --git a/data/sbx_cli/sbx_secret_rm.yaml b/data/sbx_cli/sbx_secret_rm.yaml new file mode 100644 index 0000000000..06ab46132e --- /dev/null +++ b/data/sbx_cli/sbx_secret_rm.yaml @@ -0,0 +1,32 @@ +name: sbx secret rm +synopsis: Remove a secret +usage: sbx secret rm [-g | sandbox] [service] [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: Delete without confirmation prompt + - name: global + shorthand: g + default_value: "false" + usage: Use global secret scope + - name: help + shorthand: h + default_value: "false" + usage: help for rm +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Remove a global secret + sbx secret rm -g github + + # Remove a sandbox-scoped secret + sbx secret rm my-sandbox openai + + # Remove without confirmation prompt + sbx secret rm -g github -f +see_also: + - sbx secret - Manage stored secrets diff --git a/data/sbx_cli/sbx_secret_set.yaml b/data/sbx_cli/sbx_secret_set.yaml new file mode 100644 index 0000000000..250e6a31b8 --- /dev/null +++ b/data/sbx_cli/sbx_secret_set.yaml @@ -0,0 +1,42 @@ +name: sbx secret set +synopsis: Create or update a secret +description: |- + Create or update a secret for a service. + + Available services: anthropic, aws, github, google, groq, mistral, nebius, openai, xai + + When no arguments are provided, an interactive prompt guides you through + scope and service selection. +usage: sbx secret set [-g | sandbox] [service] [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: Overwrite an existing secret when --token is used + - name: global + shorthand: g + default_value: "false" + usage: Use global secret scope + - name: help + shorthand: h + default_value: "false" + usage: help for set + - name: token + shorthand: t + usage: 'Secret value (less secure: visible in shell history)' +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Store a GitHub token globally (available to all sandboxes) + sbx secret set -g github + + # Store an OpenAI key for a specific sandbox + sbx secret set my-sandbox openai + + # Non-interactive via stdin (e.g., from a secret manager or env var) + echo "$ANTHROPIC_API_KEY" | sbx secret set -g anthropic +see_also: + - sbx secret - Manage stored secrets diff --git a/data/sbx_cli/sbx_stop.yaml b/data/sbx_cli/sbx_stop.yaml new file mode 100644 index 0000000000..97b32c1b61 --- /dev/null +++ b/data/sbx_cli/sbx_stop.yaml @@ -0,0 +1,19 @@ +name: sbx stop +synopsis: Stop one or more sandboxes without removing them +description: |- + Stop one or more running sandboxes without removing them. + + Stopped sandboxes retain their state and can be restarted with "sbx run". +usage: sbx stop SANDBOX [SANDBOX...] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for stop +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_version.yaml b/data/sbx_cli/sbx_version.yaml new file mode 100644 index 0000000000..cdab8a1f16 --- /dev/null +++ b/data/sbx_cli/sbx_version.yaml @@ -0,0 +1,15 @@ +name: sbx version +synopsis: Show Docker Sandboxes version information +usage: sbx version +options: + - name: help + shorthand: h + default_value: "false" + usage: help for version +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/summary.yaml b/data/summary.yaml index d3953bf540..b3c0639efb 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -195,6 +195,8 @@ Docker Pass: availability: Beta Docker Projects: availability: Beta +Docker Sandboxes sbx: + availability: Experimental Docker Sandboxes: availability: Experimental requires: Docker Desktop [4.58](/manuals/desktop/release-notes.md#4580) or later diff --git a/hugo.yaml b/hugo.yaml index f7f95da3fd..70878452bf 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -30,6 +30,13 @@ cascade: - target: path: /reference/cli/docker/** layout: cli + # sbx CLI reference pages use the sbx-cli layout (cobra/doc YAML) + - target: + path: /reference/cli/sbx + layout: sbx-cli + - target: + path: /reference/cli/sbx/** + layout: sbx-cli # Remove the /manuals prefix for content in the manuals section permalinks: diff --git a/layouts/sbx-cli.html b/layouts/sbx-cli.html new file mode 100644 index 0000000000..654b61d31b --- /dev/null +++ b/layouts/sbx-cli.html @@ -0,0 +1,179 @@ +{{ define "article" }} + {{ $data := index site.Data.sbx_cli .Params.datafile }} + + {{ .Store.Set "headings" slice }} +
+ {{ partial "breadcrumbs.html" . }} +
+

{{ .Title }}

+
+ + {{- /* Summary table */ -}} +
+ + + {{ with $data.synopsis }} + + + + + {{ end }} + {{ with $data.usage }} + + + + + {{ end }} + +
Description{{ . }}
Usage{{ . }}
+
+ + {{- /* Description */ -}} + {{ with $data.description }} + {{ $heading := dict "level" 2 "text" "Description" }} + {{ partialCached "heading.html" $heading "sbx-cli-description" }} + {{ $.Store.Add "headings" $heading }} + {{ . | $.RenderString (dict "display" "block") }} + {{ end }} + + {{- /* Subcommands (for section pages) */ -}} + {{ if eq .Kind "section" }} + {{ $heading := dict "level" 2 "text" "Commands" }} + {{ partialCached "heading.html" $heading "sbx-cli-commands" }} + {{ $.Store.Add "headings" $heading }} + + + + + + + + + {{ range .Pages }} + {{ if .Params.datafile }} + {{ $child := index site.Data.sbx_cli .Params.datafile }} + + + + + {{ end }} + {{ end }} + +
CommandDescription
{{ .Title }}{{ $child.synopsis }}
+ {{ end }} + + {{- /* Options */ -}} + {{ with $data.options }} + {{ $opts := where . "name" "ne" "help" }} + {{ with $opts }} + {{ $heading := dict "level" 2 "text" "Options" }} + {{ partialCached "heading.html" $heading "sbx-cli-options" }} + {{ $.Store.Add "headings" $heading }} +
+ + + + + + + + + + {{ range . }} + + + {{ $skipDefault := `[],false,` }} + + + + {{ end }} + +
OptionDefaultDescription
+ {{ with .shorthand }}-{{ . }}, {{ end }}--{{ .name }} + + {{ with .default_value }} + {{ cond (in $skipDefault .) "" (printf "%s" . | safeHTML) }} + {{ end }} + + {{ with .usage }} + {{ strings.TrimSpace . }} + {{ end }} +
+
+ {{ end }} + {{ end }} + + {{- /* Inherited (global) options */ -}} + {{ with $data.inherited_options }} + {{ $opts := where . "name" "ne" "help" }} + {{ with $opts }} + {{ $heading := dict "level" 2 "text" "Global options" }} + {{ partialCached "heading.html" $heading "sbx-cli-global-options" }} + {{ $.Store.Add "headings" $heading }} +
+ + + + + + + + + + {{ range . }} + + + {{ $skipDefault := `[],false,` }} + + + + {{ end }} + +
OptionDefaultDescription
+ {{ with .shorthand }}-{{ . }}, {{ end }}--{{ .name }} + + {{ with .default_value }} + {{ cond (in $skipDefault .) "" (printf "%s" . | safeHTML) }} + {{ end }} + + {{ with .usage }} + {{ strings.TrimSpace . }} + {{ end }} +
+
+ {{ end }} + {{ end }} + + {{- /* Examples */ -}} + {{ with $data.example }} + {{ $heading := dict "level" 2 "text" "Examples" }} + {{ partialCached "heading.html" $heading "sbx-cli-examples" }} + {{ $.Store.Add "headings" $heading }} + {{- /* Dedent: strip up to 6 leading spaces from each line */ -}} + {{ $dedented := replaceRE `(?m)^ {2,6}` "" . }} + {{ $code := printf "```console\n%s\n```" (strings.TrimSpace $dedented) }} + {{ $code | $.RenderString (dict "display" "block") }} + {{ end }} + +
+{{ end }} + +{{ define "right" }} + +{{ end }}