diff --git a/content/get-started/tutorials/run-an-agent.md b/content/get-started/tutorials/run-an-agent.md index a739ace588b9..852b764c205e 100644 --- a/content/get-started/tutorials/run-an-agent.md +++ b/content/get-started/tutorials/run-an-agent.md @@ -18,7 +18,9 @@ daemon. Your project remains available on your host, while tools the agent installs and system changes it makes stay inside an environment you can discard. -In this tutorial, you'll move an existing coding-agent workflow into a sandbox. +In this tutorial, you'll move an existing coding-agent workflow into a local +sandbox. For a cloud workflow, see +[Get started with cloud sandboxes](/manuals/ai/sandboxes/cloud/_index.md#get-started). ## Before you start diff --git a/content/includes/sandboxes-local-scope.md b/content/includes/sandboxes-local-scope.md new file mode 100644 index 000000000000..d65bb3899170 --- /dev/null +++ b/content/includes/sandboxes-local-scope.md @@ -0,0 +1,2 @@ +This page describes local sandboxes. For cloud behavior and limitations, see +[Compare local and cloud sandboxes](/manuals/ai/sandboxes/cloud/local-vs-cloud.md). diff --git a/content/manuals/agentic-platform/_index.md b/content/manuals/agentic-platform/_index.md index 38baaac6ca35..946bc36daa6e 100644 --- a/content/manuals/agentic-platform/_index.md +++ b/content/manuals/agentic-platform/_index.md @@ -47,8 +47,11 @@ sandboxes on Docker-managed cloud infrastructure. An active workload is not tied to your computer remaining awake or connected. You can leave the Console and return to the sandbox while the agent continues working. -For sandboxes that run on your development machine through the `sbx` CLI, see -[Docker Sandboxes](/manuals/ai/sandboxes/_index.md). +The `sbx` CLI supports both +[local sandboxes](/manuals/ai/sandboxes/get-started.md) and +[cloud sandboxes](/manuals/ai/sandboxes/cloud/_index.md). These pages describe +the web Console experience. The Console and CLI use different secret names; +see [Cloud credentials](/manuals/ai/sandboxes/cloud/credentials.md). From the web Console, choose the type of sandbox to run and configure its model credential, network access, tools, and compute. Docker creates the sandbox and diff --git a/content/manuals/agentic-platform/faq.md b/content/manuals/agentic-platform/faq.md index 7217e164f968..19667ce13d96 100644 --- a/content/manuals/agentic-platform/faq.md +++ b/content/manuals/agentic-platform/faq.md @@ -17,14 +17,18 @@ Docker-hosted sandbox with a live terminal. ## How does Docker Agentic Platform differ from Docker Sandboxes? Docker Agentic Platform runs sandboxes on Docker-managed cloud infrastructure -through a web Console. Docker Sandboxes runs sandboxes on your development -machine through the `sbx` command. Docker Agentic Platform manages the compute, -MCP connections, secrets, and network policies used by its hosted sandboxes. +through a web Console. The `sbx` CLI runs local sandboxes on your development +machine and cloud sandboxes with `sbx --cloud`. The Console and CLI have +different workflows and secret names. See +[Cloud sandboxes](/manuals/ai/sandboxes/cloud/_index.md) for the CLI experience. ## Can I move a sandbox between my machine and Docker Agentic Platform? -No. Local and hosted sandboxes are separate in the initial release. You cannot -move a running sandbox or its local bind mounts into Docker Agentic Platform. +The `sbx move` command copies a sandbox filesystem between local and cloud +environments. It does not transfer running processes, host bind mounts, or +managed secrets, and it leaves the source sandbox in place. See +[Move a sandbox](/manuals/ai/sandboxes/cloud/move.md) for the CLI workflow and +its limitations. ## Can I share sandboxes and configuration with a team? diff --git a/content/manuals/ai-overview.md b/content/manuals/ai-overview.md index c5b86da62b20..d573235ae475 100644 --- a/content/manuals/ai-overview.md +++ b/content/manuals/ai-overview.md @@ -33,10 +33,11 @@ in YAML. You configure agents with specific roles, models, and tools, then run them from your terminal. Docker Agent is a general-purpose agent runtime, not specific to Docker tasks. -**Docker Sandboxes** provides isolated microVM environments for running coding -agents. It supports multiple agents including Claude Code, Codex, Copilot, -Devin, Gemini, and Docker Agent. Sandboxes is the isolation layer — the agents -themselves are separate tools. +Docker Sandboxes provides isolated environments for running coding agents +[locally](./ai/sandboxes/get-started.md) or +[in the cloud](./ai/sandboxes/cloud/_index.md). Sandboxes is the isolation layer; +the agents themselves are separate tools. Agent configuration and supported +features differ between local and cloud sandboxes. **Model Runner** lets you run LLMs locally. Other tools like Docker Agent can use Model Runner as a model provider. diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index 1db8a83b1c8c..5c6968222157 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/content/manuals/ai/sandboxes/_index.md @@ -8,37 +8,39 @@ params: group: AI and agents --- -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 accessing host -resources beyond those you share. +Docker Sandboxes run AI coding agents in isolated environments on your machine +or on Docker-managed cloud infrastructure. Use the `sbx` CLI to create and +manage either kind of sandbox. -> [!NOTE] -> The `sbx` CLI is free to use, including for commercial work. Only -> [organization governance](governance/) requires a separate paid subscription. +The `sbx` CLI and local sandbox compute are free to use, including for commercial +work. Cloud compute is metered through a +[Docker Agentic Platform plan](/manuals/subscription-billing/plans/docker-agentic-platform.md). +Model-provider charges are separate. Organization admins can [centrally manage sandbox network, filesystem, and MCP policies](governance/access-controls/organization.md), -so the same controls apply uniformly across every developer's machine. +for local sandboxes across developer machines. Available on a separate paid subscription. ## Get started -Follow the [installation guide](install.md) to check the system requirements, -install the `sbx` CLI, and sign in. +[Install the `sbx` CLI](install.md) and sign in, then choose where to run your +agent: -Then launch an agent in a sandbox: +| Environment | Use it for | Start here | +| --- | --- | --- | +| Local sandboxes | Work with files and supported hardware on your machine | [Get started locally](get-started.md) | +| Cloud sandboxes | Run on Docker-managed compute without local virtualization | [Get started in the cloud](cloud/_index.md#get-started) | -```console -$ cd ~/my-project -$ sbx run claude -``` - -See the [get started guide](get-started.md) for a first-session walkthrough, or -jump to the [usage guide](usage.md) for basic commands. +The two environments have separate credentials, network policies, and lifecycle +controls. See [Compare local and cloud sandboxes](cloud/local-vs-cloud.md) +before adapting a workflow. ## Learn more +The following guides describe local sandbox workflows. For cloud workflows, +see [Cloud sandboxes](cloud/). + - [Agents](agents/) — supported agents and per-agent configuration - [Workflows](workflows/) — patterns for Git, local development, authentication, agent skills, and automation diff --git a/content/manuals/ai/sandboxes/agents/_index.md b/content/manuals/ai/sandboxes/agents/_index.md index 7ed96291c0f1..8d0cdbb4d3b3 100644 --- a/content/manuals/ai/sandboxes/agents/_index.md +++ b/content/manuals/ai/sandboxes/agents/_index.md @@ -6,7 +6,7 @@ description: AI coding agents supported by Docker Sandboxes. keywords: docker sandboxes, ai agents, claude code, codex, cursor, devin, gemini --- -Docker Sandboxes runs the following agents out of the box: +Docker Sandboxes runs the following agents in local sandboxes: - [Claude Code](claude-code/) - [Codex](codex/) diff --git a/content/manuals/ai/sandboxes/agents/claude-code.md b/content/manuals/ai/sandboxes/agents/claude-code.md index e2df6832f6db..c50f8f47a7db 100644 --- a/content/manuals/ai/sandboxes/agents/claude-code.md +++ b/content/manuals/ai/sandboxes/agents/claude-code.md @@ -7,6 +7,10 @@ description: | keywords: docker sandboxes, claude code, anthropic, ai agent, sbx, local models, llmman, ollama --- +The following instructions apply to local sandboxes. For cloud authentication +and usage, see [Authenticate cloud agents](../cloud/credentials.md) and +[Use cloud sandboxes](../cloud/usage.md). + Official documentation: [Claude Code](https://code.claude.com/docs) ## Quick start diff --git a/content/manuals/ai/sandboxes/agents/codex.md b/content/manuals/ai/sandboxes/agents/codex.md index ccde6e99db92..ded1ae781861 100644 --- a/content/manuals/ai/sandboxes/agents/codex.md +++ b/content/manuals/ai/sandboxes/agents/codex.md @@ -7,6 +7,8 @@ description: | keywords: docker sandboxes, codex, openai, ai agent, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of Codex in a sandboxed environment. diff --git a/content/manuals/ai/sandboxes/agents/copilot.md b/content/manuals/ai/sandboxes/agents/copilot.md index 08e9bbd224ba..250e684ee582 100644 --- a/content/manuals/ai/sandboxes/agents/copilot.md +++ b/content/manuals/ai/sandboxes/agents/copilot.md @@ -7,6 +7,8 @@ description: | keywords: docker sandboxes, github copilot, ai agent, github token, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of GitHub Copilot in a sandboxed environment. diff --git a/content/manuals/ai/sandboxes/agents/cursor.md b/content/manuals/ai/sandboxes/agents/cursor.md index cfcbfa3c5544..65b1d650f85e 100644 --- a/content/manuals/ai/sandboxes/agents/cursor.md +++ b/content/manuals/ai/sandboxes/agents/cursor.md @@ -7,6 +7,8 @@ description: | keywords: docker sandboxes, cursor, cursor agent, ai agent, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of Cursor in a sandboxed environment. diff --git a/content/manuals/ai/sandboxes/agents/devin.md b/content/manuals/ai/sandboxes/agents/devin.md index 18c2f7cb0b2a..349c73c0ebc2 100644 --- a/content/manuals/ai/sandboxes/agents/devin.md +++ b/content/manuals/ai/sandboxes/agents/devin.md @@ -5,6 +5,8 @@ description: Use Devin CLI in Docker Sandboxes with reusable, proxy-managed auth keywords: docker sandboxes, devin, cognition, ai agent, sbx --- +{{% include "sandboxes-local-scope.md" %}} + Official documentation: [Devin CLI](https://docs.devin.ai/work-with-devin/devin-cli) ## Quick start diff --git a/content/manuals/ai/sandboxes/agents/docker-agent.md b/content/manuals/ai/sandboxes/agents/docker-agent.md index 656d1488e38b..788ac1b23a69 100644 --- a/content/manuals/ai/sandboxes/agents/docker-agent.md +++ b/content/manuals/ai/sandboxes/agents/docker-agent.md @@ -7,6 +7,8 @@ description: | keywords: docker sandboxes, docker agent, openai, anthropic, sbx --- +{{% include "sandboxes-local-scope.md" %}} + Official documentation: [Docker Agent](/manuals/ai/docker-agent/_index.md) ## Quick start diff --git a/content/manuals/ai/sandboxes/agents/droid.md b/content/manuals/ai/sandboxes/agents/droid.md index e74e648bce27..8e1687b08271 100644 --- a/content/manuals/ai/sandboxes/agents/droid.md +++ b/content/manuals/ai/sandboxes/agents/droid.md @@ -6,6 +6,8 @@ description: | keywords: docker sandboxes, droid, factory, ai agent, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of Droid, an AI coding agent by Factory, in a sandboxed environment. diff --git a/content/manuals/ai/sandboxes/agents/gemini.md b/content/manuals/ai/sandboxes/agents/gemini.md index bbf5275b9f41..e1723ee1ee3d 100644 --- a/content/manuals/ai/sandboxes/agents/gemini.md +++ b/content/manuals/ai/sandboxes/agents/gemini.md @@ -7,6 +7,8 @@ description: | keywords: docker sandboxes, gemini, google, ai agent, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of Google Gemini in a sandboxed environment. diff --git a/content/manuals/ai/sandboxes/agents/kiro.md b/content/manuals/ai/sandboxes/agents/kiro.md index 47932e2a7fcc..82de9fdcdeae 100644 --- a/content/manuals/ai/sandboxes/agents/kiro.md +++ b/content/manuals/ai/sandboxes/agents/kiro.md @@ -7,6 +7,8 @@ description: | keywords: docker sandboxes, kiro, ai agent, authentication, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of Kiro in a sandboxed environment. diff --git a/content/manuals/ai/sandboxes/agents/opencode.md b/content/manuals/ai/sandboxes/agents/opencode.md index 9ead950118be..498602480d5b 100644 --- a/content/manuals/ai/sandboxes/agents/opencode.md +++ b/content/manuals/ai/sandboxes/agents/opencode.md @@ -7,6 +7,8 @@ description: | keywords: docker sandboxes, opencode, ai agent, authentication, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of OpenCode in a sandboxed environment. diff --git a/content/manuals/ai/sandboxes/agents/shell.md b/content/manuals/ai/sandboxes/agents/shell.md index 5e26f6c8f94d..d8416a295d58 100644 --- a/content/manuals/ai/sandboxes/agents/shell.md +++ b/content/manuals/ai/sandboxes/agents/shell.md @@ -5,6 +5,8 @@ description: Run an agent-less sandbox with a Bash login shell for manual setup, keywords: sandboxes, sbx, shell, agent, manual setup, testing --- +{{% include "sandboxes-local-scope.md" %}} + `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 diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index 7a02fbd4e3bd..d9a7d3d591c3 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -5,6 +5,8 @@ description: Technical architecture of Docker Sandboxes; workspace mounting, sto keywords: docker sandboxes, architecture, microVM, workspace mounting, sandbox lifecycle --- +{{% include "sandboxes-local-scope.md" %}} + This page explains how Docker Sandboxes work under the hood. For the security properties of the architecture, see [Sandbox isolation](security/isolation.md). diff --git a/content/manuals/ai/sandboxes/cloud/_index.md b/content/manuals/ai/sandboxes/cloud/_index.md new file mode 100644 index 000000000000..b2c31e8211a3 --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/_index.md @@ -0,0 +1,107 @@ +--- +title: Cloud sandboxes +description: Run Docker Sandboxes on Docker-managed cloud infrastructure and understand the cloud-specific command, storage, and billing model. +keywords: docker sandboxes, cloud sandboxes, sbx cloud, ai agents, agentic platform +weight: 35 +--- + +Cloud sandboxes run AI agents on Docker-managed infrastructure instead of your +local machine. Use them when you need an isolated environment that doesn't +depend on the compute resources or virtualization support of your host. + +Cloud sandboxes use the same `sbx` CLI as local sandboxes. Add the global +`--cloud` flag to send a supported command to the Cloud Sandboxes API: + +```console +$ sbx --cloud ls +``` + +Cloud and local sandboxes have separate state and different capabilities. A +cloud sandbox can't mount a host workspace or use host hardware, and its +secrets, network policy, ports, and lifecycle are managed in the cloud. See +[Local and cloud differences](local-vs-cloud.md) before adapting a local +workflow. + +## Prerequisites + +To use cloud sandboxes, you need: + +- The [`sbx` CLI](../install.md), version 0.42.0 or later +- A Docker account signed in through `sbx login` +- An active [Docker Agentic Platform plan](/manuals/subscription-billing/plans/docker-agentic-platform.md) + +To subscribe, open [Docker Agentic Platform](https://agentic-platform.docker.com/) +and sign in. The plan is available for Docker Personal and Docker Pro accounts. + +Cloud sandbox compute is metered through the Docker Agentic Platform +pay-as-you-go plan. Inference charges aren't included. Your model provider +charges for requests made with the API keys or OAuth credentials that you +configure. + +## Get started + +Credentials configured for local sandboxes aren't available to cloud +sandboxes. Configure a cloud credential for your agent before launching it. +For Claude Code, store an Anthropic API key: + +```console +$ sbx --cloud secret set anthropic +``` + +Cloud sandboxes expire after one hour by default and are deleted when they +expire. Copy out work you want to keep before expiration. For other timeout +options, see [Configure expiration](usage.md#configure-expiration). + +Create a sandbox without attaching, allowing access to GitHub for this example: + +```console +$ sbx --cloud create --name cloud-project --allow-network github.com:443 claude +``` + +Cloud sandboxes don't accept a local workspace path. Clone the public +[Welcome to Docker repository](https://github.com/docker/welcome-to-docker) +inside the sandbox: + +```console +$ sbx --cloud exec cloud-project git clone \ + https://github.com/docker/welcome-to-docker.git /home/agent/workspace/project +``` + +Attach to the agent: + +```console +$ sbx --cloud attach cloud-project +``` + +Ask Claude to inspect `/home/agent/workspace/project` and write a description +of the application to `/home/agent/workspace/review.md`. When the file is ready, +press `Ctrl+\` to detach and leave the agent running. + +Copy the result to your machine: + +```console +$ sbx --cloud cp cloud-project:/home/agent/workspace/review.md ./review.md +``` + +Read the result, then remove the sandbox when you're finished: + +```console +$ sbx --cloud rm cloud-project +``` + +Removal deletes files stored only in the sandbox. For your own projects, see +[Transfer files](usage.md#transfer-files) and +[Authenticate cloud agents](credentials.md) before cloning private repositories. + +## Learn more + +- [Local and cloud differences](local-vs-cloud.md) compares the two execution + environments +- [Use cloud sandboxes](usage.md) covers creation, files, ports, and lifecycle +- [Authenticate cloud agents](credentials.md) covers cloud-specific secrets, + API keys, and OpenAI OAuth +- [Manage cloud network policy](network-policy.md) covers account-level and + sandbox-level network access +- [Move a sandbox](move.md) explains filesystem transfers between local and + cloud environments +- [`sbx` CLI reference](/reference/cli/sbx/) lists commands and options diff --git a/content/manuals/ai/sandboxes/cloud/credentials.md b/content/manuals/ai/sandboxes/cloud/credentials.md new file mode 100644 index 000000000000..9f2100b1436c --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/credentials.md @@ -0,0 +1,122 @@ +--- +title: Authenticate cloud agents +linkTitle: Credentials +description: Configure cloud-specific API keys and OAuth credentials for agents without storing credentials in the cloud sandbox filesystem. +keywords: docker sandboxes, cloud credentials, cloud secrets, oauth, anthropic, openai +weight: 30 +--- + +Cloud agents authenticate with credentials from the cloud secret store. Set up +these credentials before launching an agent so authentication doesn't depend +on files stored inside the sandbox. + +## Use the cloud secret store + +The following secret interfaces are separate: + +- `sbx secret` manages secrets for local sandboxes +- `sbx --cloud secret` manages secrets for cloud sandboxes created by the CLI +- Docker Agentic Platform manages its own secret names through its web + interface + +A credential created through one interface isn't available through the +others. If you already configured an Anthropic or OpenAI credential for local +sandboxes, configure it again with `sbx --cloud secret` before starting a +cloud sandbox. + +## Choose an authentication method + +Claude Code in cloud sandboxes requires an Anthropic API key. Anthropic OAuth +and Claude subscription sign-in are not supported for cloud sandboxes. + +Configure your agent with the corresponding command: + +| Agent or provider | Recommended command | Authentication | +| --- | --- | --- | +| Claude Code | `sbx --cloud secret set anthropic` | Prompts for an Anthropic API key | +| Codex with OpenAI OAuth | `sbx --cloud secret set openai --oauth` | Opens the OpenAI OAuth flow and stores the resulting credential at account scope | +| Service API key | `sbx --cloud secret set ` | Prompts for an API key or token | + +For Codex, you can use OpenAI OAuth at account scope or store an OpenAI API +key with `sbx --cloud secret set openai`. + +After storing the Anthropic API key, launch Claude Code: + +```console +$ sbx --cloud run claude --name cloud-project +``` + +## Keep credentials out of the sandbox filesystem + +Credentials configured with `sbx --cloud secret` stay in the cloud secret store, +outside the sandbox filesystem. + +An agent's interactive sign-in can write credentials inside the sandbox. +Those files can be included in templates and `sbx move` snapshots. If you +signed in inside an agent, follow the provider's sign-out guidance and remove +those credentials before capturing or moving the sandbox. + +## Set credential scope + +Credentials use account scope by default. An account-scoped credential is +available to cloud sandboxes in the Docker account: + +```console +$ sbx --cloud secret set github +``` + +Scope an API key or token to one sandbox by name: + +```console +$ sbx --cloud secret set openai --sandbox cloud-project +``` + +A sandbox-scoped secret takes precedence over an account-scoped secret for the +same service. Set it before creating the sandbox so the CLI can include it when +the sandbox starts. OAuth credentials can't use sandbox scope. + +## Service identifiers + +The following table shows cloud secret support for the +[built-in services documented for local sandboxes](../configuration/credentials.md#built-in-services): + +| Service | Cloud secret authentication | +| --- | --- | +| `anthropic` | API key | +| `cursor` | Not supported | +| `droid` | API key; cloud-managed OAuth is not supported | +| `github` | Token | +| `google` | API key | +| `groq` | API key | +| `mistral` | API key | +| `nebius` | API key | +| `openai` | API key or OAuth | +| `openrouter` | Not supported | +| `xai` | API key | + +To configure a supported service, run `sbx --cloud secret set `. +For OpenAI OAuth, add `--oauth` and use account scope. An agent's interactive +sign-in does not use the cloud secret store. + +Services declared by local kits aren't automatically supported in cloud +sandboxes. A kit cannot add a service to the cloud secret store. + +Registry credentials, dynamic `--ref` values, and host-run `--command` +resolvers aren't cloud secret workflows. + +## List and remove credentials + +List cloud secret metadata without revealing values: + +```console +$ sbx --cloud secret ls +``` + +Remove a credential from the matching scope: + +```console +$ sbx --cloud secret rm github +$ sbx --cloud secret rm openai --sandbox cloud-project +``` + +Cloud mode doesn't support removing every secret in one operation. diff --git a/content/manuals/ai/sandboxes/cloud/local-vs-cloud.md b/content/manuals/ai/sandboxes/cloud/local-vs-cloud.md new file mode 100644 index 000000000000..54a46d6acbb2 --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/local-vs-cloud.md @@ -0,0 +1,49 @@ +--- +title: Compare local and cloud sandboxes +linkTitle: Local and cloud +description: Compare local and cloud Docker Sandboxes, including workspaces, host integrations, ports, secrets, storage, and lifecycle behavior. +keywords: docker sandboxes, local sandbox, cloud sandbox, sbx cloud, comparison +weight: 10 +--- + +Local and cloud sandboxes provide isolated environments for AI agents, but +they run against different resources and stores. This comparison helps you +choose an environment and identify workflows that need cloud-specific setup. + +| Capability | Local sandbox | Cloud sandbox | +| --- | --- | --- | +| Compute | Uses resources from the host | Uses Docker-managed cloud resources | +| Workspace | Mounts host paths or uses a private Git clone backed by the host repository | Has no access to host paths; transfer files or clone a repository inside the sandbox | +| Hardware | Can use supported host integrations, such as GPU, USB, display, and nested virtualization | Has no access to host hardware | +| Ports | Binds sandbox ports to host addresses and ports | Exposes a sandbox port through a public HTTPS URL | +| Secrets | Reads from the local `sbx` secret store | Reads from the separate `sbx --cloud` secret store | +| Network policy | Uses local and organization policy sources supported by the local runtime | Uses separate, network-only account and sandbox policy with organization governance unavailable in this release | +| Storage | Persists in the local sandbox and its attached host resources | Persists in the cloud sandbox and optional cloud volumes | +| Lifetime | Persists across stops until you remove it | Expires according to its time-to-live and timeout action | +| Billing | No metered sandbox compute charge | Metered through the Docker Agentic Platform plan | + +## Host-dependent features + +A cloud sandbox has no path back to the machine where you run `sbx`. The +following local features don't apply in cloud mode: + +- Workspace paths, bind mounts, `--clone`, and Git worktrees created with + `--branch` +- GPU, USB, display, and nested virtualization options +- Models served by a local model runtime +- Host port bindings +- Declarative `sbx env` workflows using `sbxenv.yaml` +- Host-backed agent skills and the full local MCP management workflow + +The CLI rejects local-only flags used with `--cloud` instead of ignoring them. + +## Separate resources + +Adding `--cloud` changes the backend for the command. A sandbox shown by +`sbx ls` doesn't appear in `sbx --cloud ls`, and resources created for one +backend don't automatically become available to the other. + +This separation applies to sandboxes, templates, secrets, volumes, and network +policy. Use [`sbx move`](move.md) when you need to copy a sandbox filesystem +between backends. Moving doesn't unify the resource stores or transfer +host-mounted files and secrets. diff --git a/content/manuals/ai/sandboxes/cloud/move.md b/content/manuals/ai/sandboxes/cloud/move.md new file mode 100644 index 000000000000..12f0baff6813 --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/move.md @@ -0,0 +1,104 @@ +--- +title: Move a sandbox +description: Transfer a Docker Sandbox filesystem between local and cloud environments and understand which state, files, policies, and secrets remain behind. +keywords: docker sandboxes, sbx move, cloud sandbox, local sandbox, migrate sandbox +weight: 50 +--- + +The `sbx move` command transfers a filesystem snapshot between a local sandbox +and a cloud sandbox. Use it to continue from the captured filesystem in the +other environment, not as a live migration of the running sandbox. + +## Transfer behavior + +A move performs the following operations: + +1. Captures the source sandbox filesystem as a template image +2. Transfers the image across the local and cloud boundary +3. Creates a destination sandbox from the image + +The destination gets a different sandbox ID. The source isn't deleted, so the +two sandboxes have independent state after the transfer. A local-to-cloud move +stops the local source while capturing it. A cloud-to-local move attempts to +stop the cloud source after creating the destination. This is a best-effort +operation, so the cloud source can remain running if it can't be stopped. +Remove the source separately after you verify the destination. + +> [!IMPORTANT] +> +> Managed secrets aren't copied from the source secret store. Credentials +> written inside a sandbox by an agent's interactive sign-in are ordinary +> filesystem files and are included in the snapshot. Remove in-sandbox +> credentials before moving a sandbox. + +Moving transfers filesystem data stored in the sandbox container. It doesn't +transfer: + +- Running processes, memory, or open sockets +- Local workspace mounts, bind mounts, or clone-mode volumes +- Managed secrets from the source secret store +- Other resources attached outside the sandbox filesystem + +Changes made to either sandbox after the move aren't synchronized. + +The snapshot retains the source sandbox's platform. The destination must +support the same platform because `sbx move` doesn't convert between +`linux/amd64` and `linux/arm64`. For a local-to-cloud move, your cloud account +must support the local sandbox's platform. For a cloud-to-local move, create +the cloud sandbox with the platform used by your local sandbox runtime. + +## Move from local to cloud + +Move a local sandbox to the cloud: + +```console +$ sbx move local-project --to cloud +``` + +The `move` command spans both backends, so don't add the global `--cloud` flag. +Use `--name` to set the destination name: + +```console +$ sbx move local-project --to cloud --name cloud-project +``` + +Local workspace files are mounted outside the sandbox filesystem and don't +appear in the cloud destination. When the source has a workspace, the CLI +warns and asks for confirmation. The `--force` flag skips the prompt but +doesn't include those files. + +The destination receives the applicable allow and deny network rules from the +local source. Published TCP sandbox ports are also published on the cloud +destination on a best-effort basis. Host port numbers and non-TCP mappings +don't transfer. + +The destination can use applicable credentials that already exist in the cloud +secret store. Credentials in the local secret store don't transfer. + +## Move from cloud to local + +Move a cloud sandbox to the local runtime by ID or name: + +```console +$ sbx move cloud-project --to local --name local-copy +``` + +The local destination starts with the host's default network policy. Cloud +network rules aren't copied back to the local runtime. + +This direction requires a machine that meets the local sandbox requirements +because the command imports the snapshot and creates a local sandbox. The +cloud source remains available unless you remove it with `sbx --cloud rm`. + +## Verify the result + +List both backends after the move: + +```console +$ sbx ls +$ sbx --cloud ls +``` + +Inspect the destination filesystem and verify its credentials, ports, volumes, +and other environment-specific resources before removing the source. Configure +anything that didn't carry over. diff --git a/content/manuals/ai/sandboxes/cloud/network-policy.md b/content/manuals/ai/sandboxes/cloud/network-policy.md new file mode 100644 index 000000000000..fba0090a5150 --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/network-policy.md @@ -0,0 +1,122 @@ +--- +title: Manage cloud network policy +linkTitle: Network policy +description: Control outbound connections from Docker cloud sandboxes with account-level and sandbox-level allow and deny network rules. +keywords: docker sandboxes, cloud network policy, sbx cloud, allow network, deny network +weight: 40 +--- + +Cloud network policy controls outbound connections from cloud sandboxes. It is +a separate, network-only policy store with Docker account and individual +sandbox scopes. + +> [!IMPORTANT] +> +> Organization governance is not available for cloud sandboxes in this +> release. Configure cloud rules with `sbx --cloud policy` and verify network +> access using connection checks and policy logs. + +## Understand policy scope + +The cloud CLI supports account and sandbox policy scopes. Your account policy +supplies the default for cloud sandboxes you create in the Docker account. A +sandbox policy adds rules for one cloud sandbox. Matching deny rules take +precedence over allow rules across the applicable policies. + +When a local sandbox daemon is available, `sbx --cloud create` reads active +network rules from its local policy store and copies them into the cloud +sandbox's initial policy. This point-in-time copy can include organization +rules that were synchronized to that machine. It doesn't make the cloud +sandbox organization-governed, and later organization policy changes don't +update the copied cloud rules. + +This copy applies only to `sbx --cloud create`. A sandbox created by +`sbx --cloud run` doesn't read the local policy store. It uses cloud account +policy, network rules passed to the command, and network access declared by the +agent or kit. + +Define the intended policy in the cloud store. After creation, inspect the +configured rules and [verify connection decisions](#inspect-network-policy). +Don't treat copied local rules as a central enforcement boundary. + +## Initialize account policy + +Initialize the account policy with an allow-all or deny-all default: + +```console +$ sbx --cloud policy init deny-all +``` + +The default applies to your cloud sandboxes in the Docker account. You can add +rules after initialization or specify initial rules when creating a sandbox. +A deny-all default still permits destinations allowed by applicable sandbox +or agent-kit rules. + +## Add network rules + +Add an account-level exception: + +```console +$ sbx --cloud policy allow network api.github.com:443 +``` + +Scope a rule to one sandbox: + +```console +$ sbx --cloud policy allow network api.anthropic.com:443 \ + --sandbox cloud-project +``` + +Deny rules take precedence when the same destination matches both an allow +rule and a deny rule. + +You can also add initial rules while creating a sandbox: + +```console +$ sbx --cloud create --name cloud-project \ + --allow-network api.github.com:443 \ + --deny-network example.com claude +``` + +## Inspect network policy + +Inspect your account policy or a sandbox's configured policy: + +```console +$ sbx --cloud policy ls +$ sbx --cloud policy ls cloud-project +``` + +The sandbox view shows its policy document, or your account default when the +sandbox has no policy document. It does not show the complete combination of +applicable rules. + +To verify enforcement, attempt the connection from the sandbox, then review +the connection decisions: + +```console +$ sbx --cloud exec cloud-project curl -I https://api.github.com +$ sbx --cloud policy log cloud-project +``` + +These records describe cloud network policy decisions. They aren't Docker AI +Governance organization audit logs. + +## Remove network rules + +Use `sbx --cloud policy rm network` to remove an individual rule. Run the +command with `--help` to see the resource and scope options: + +```console +$ sbx --cloud policy rm network --help +``` + +Reset your account policy to deny-all and remove its rules: + +```console +$ sbx --cloud policy reset +``` + +Sandbox-specific policies remain in place and can still grant access. Inspect +those policies separately. In `sbx` version 0.42.0, the reset command prints +"reset to allow-all", but the service resets the account policy to deny-all. diff --git a/content/manuals/ai/sandboxes/cloud/usage.md b/content/manuals/ai/sandboxes/cloud/usage.md new file mode 100644 index 000000000000..233b8552efff --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/usage.md @@ -0,0 +1,243 @@ +--- +title: Use cloud sandboxes +description: Create and manage Docker cloud sandboxes with the sbx CLI, including file transfer, commands, ports, storage, and lifecycle controls. +keywords: docker sandboxes, cloud sandbox, sbx cloud, cloud ports, sandbox ttl +weight: 20 +--- + +Use the `--cloud` flag with supported `sbx` commands to create and manage +sandboxes on Docker-managed infrastructure. Cloud operations use cloud IDs, +names, resources, and lifecycle controls rather than the local sandbox daemon. + +## Create a sandbox + +A cloud sandbox expires after one hour by default and is deleted on expiration. +See [Configure expiration](#configure-expiration) to choose another timeout or +action before creating it. + +Credentials saved for local sandboxes aren't available in cloud sandboxes. +[Configure a cloud credential](credentials.md) before launching an agent. + +Create a sandbox and attach to its agent: + +```console +$ sbx --cloud run claude --name cloud-project +``` + +To create the sandbox without opening an agent session, use `create`: + +```console +$ sbx --cloud create --name cloud-project claude +``` + +The command prints the cloud sandbox ID. Attach by ID or name: + +```console +$ sbx --cloud attach cloud-project +``` + +Without resource flags, a cloud sandbox starts with 2 CPUs and 4 GiB of +memory. Use `--cpus` and `--memory` to select another supported configuration. + +Cloud creation doesn't accept workspace paths. For example, +`sbx --cloud run claude .` returns an error because `.` refers to the local +filesystem. + +## Run without attaching + +For scripts or terminals without interactive input, create and start an agent +without attaching: + +```console +$ sbx --cloud run --detached claude --name cloud-task +``` + +A detached run creates a fresh sandbox. It does not resume a stopped sandbox. +Use `sbx --cloud exec` to run commands and `sbx --cloud rm` to clean up. + +To detach from an interactive `run` or `attach` session while leaving the +agent running, press `Ctrl+\`. Reconnect with `sbx --cloud attach `. + +## List and inspect sandboxes + +List cloud sandboxes separately from local sandboxes: + +```console +$ sbx --cloud ls +``` + +Most cloud commands accept either the sandbox name or the `sbx_`-prefixed ID +shown in the output. + +## Run commands + +Run a command inside a cloud sandbox: + +```console +$ sbx --cloud exec cloud-project pwd +``` + +## Connect with SSH + +Configure cloud SSH access and connect with your SSH client: + +```console +$ sbx --cloud setup ssh +$ ssh sbx_01abc123@sbx_cloud +``` + +Replace the example with `ssh @sbx_cloud`, using the +`sbx_`-prefixed ID from `sbx --cloud ls`. + +## Transfer files + +Use `sbx --cloud cp` to copy files or directories between the client machine +and a cloud sandbox. Use absolute sandbox paths: + +```console +$ sbx --cloud cp ./src cloud-project:/home/agent/workspace/src +$ sbx --cloud cp cloud-project:/home/agent/workspace/result.json ./result.json +``` + +Copying creates a point-in-time transfer. It doesn't mount or synchronize the +local path. For source control workflows, you can also clone a remote +repository from inside the sandbox and push changes to the remote. Configure +[cloud credentials](credentials.md) before creating a sandbox that needs access +to a private repository. The [cloud walkthrough](_index.md#get-started) shows a +public repository example. + +## Expose a port + +Expose a TCP service by specifying its sandbox port: + +```console +$ sbx --cloud ports cloud-project --publish 8080 +``` + +The command returns a public HTTPS URL assigned by the cloud control plane. +Cloud mode accepts only the sandbox port number. Host IP addresses, host port +numbers, and protocol suffixes don't apply. + +List or remove exposed ports: + +```console +$ sbx --cloud ports cloud-project +$ sbx --cloud ports cloud-project --unpublish 8080 +``` + +Treat an exposed URL as a public endpoint. Apply authentication in the service +and remove the exposure when you no longer need it. + +## Configure expiration + +Set the time-to-live and the action taken when it lapses during creation: + +```console +$ sbx --cloud create --name cloud-project --ttl 2h --on-timeout delete claude +``` + +The default time-to-live is one hour, and the default timeout action is +`delete`. The `stop` action preserves the sandbox so it can be started again. +Volume-backed sandboxes require the `delete` action. + +Inspect or extend the expiration. Extensions cannot move expiration beyond +24 hours from creation: + +```console +$ sbx --cloud ttl cloud-project +$ sbx --cloud ttl +30m cloud-project +``` + +## Stop or remove a sandbox + +Stop a cloud sandbox without deleting its filesystem: + +```console +$ sbx --cloud stop cloud-project +``` + +Compute isn't billed while a sandbox is stopped. To resume it, run the agent +again and select the stopped sandbox when prompted: + +```console +$ sbx --cloud run claude +``` + +Resuming keeps the sandbox ID and state and sets expiration to one hour after +resume. Inspect it with `sbx --cloud ttl cloud-project`. The `attach` command +doesn't resume a stopped sandbox. A detached run creates a fresh sandbox instead +of resuming the stopped one. + +If stop or resume reports that an existing sandbox was not found, the operation +may be disabled for your account. + +Volume-backed sandboxes can't be stopped. Remove a volume-backed sandbox to end +it and save the volume snapshot. + +Remove a sandbox when you no longer need its state: + +```console +$ sbx --cloud rm cloud-project +``` + +Removal deletes the cloud sandbox and can't be undone. + +## Use persistent volumes + +Cloud volumes are experimental and preserve data independently of a sandbox. +Create a volume, then attach it at sandbox creation: + +```console +$ sbx --cloud volume create dependency-cache +$ sbx --cloud create --name cloud-project \ + --volume dependency-cache:/workspace/cache claude +``` + +The root directory of a newly created volume is owned by `root`. Change its +ownership after attaching it so the agent can write to it: + +```console +$ sbx --cloud exec cloud-project \ + sudo chown agent:agent /workspace/cache +``` + +Volume data is saved as a snapshot when a sandbox exits, not continuously. If +multiple sandboxes mount the same volume at the same time, the last sandbox to +exit overwrites the stored snapshot. + +## Customize a cloud sandbox + +Cloud templates have their own store. A local template is not available to +`sbx --cloud` until you transfer it. To capture a running cloud sandbox and +create another sandbox from that template: + +```console +$ sbx --cloud template save cloud-project cloud-template +$ sbx --cloud create --name cloud-copy --template cloud-template +``` + +The template supplies its CPU and memory configuration. Do not combine +`--template` with an agent name, `--cpus`, or `--memory`. To launch an OCI image +directly instead, use `--image-ref` with explicit CPU and memory values. + +Snapshots include credentials written to the sandbox filesystem. Remove those +credentials before saving a template. Managed cloud secrets stay in the secret +store. See [Authenticate cloud agents](credentials.md). + +Cloud sandboxes also support sandbox kits and `--kit` mixins. Kit support does +not make host mounts, shared host skills, or arbitrary credential services +available in the cloud. Check [Local and cloud differences](local-vs-cloud.md) +and configure [cloud credentials](credentials.md) before adapting a local kit. + +## Load an MCP server + +First, [connect and authorize an MCP server](/manuals/agentic-platform/mcp.md) +in Docker Agentic Platform. Then load that server into a running cloud sandbox: + +```console +$ sbx --cloud mcp load --sandbox cloud-project +``` + +The server name is resolved by the MCP gateway associated with your Docker +Agentic Platform account. Cloud sandboxes don't use servers registered in the +local MCP store with `sbx mcp add`. diff --git a/content/manuals/ai/sandboxes/configuration/_index.md b/content/manuals/ai/sandboxes/configuration/_index.md index 8f7ced2be2b5..f48ee43d332d 100644 --- a/content/manuals/ai/sandboxes/configuration/_index.md +++ b/content/manuals/ai/sandboxes/configuration/_index.md @@ -6,7 +6,7 @@ description: Configure credentials, project environments, GPU passthrough, regis keywords: docker sandboxes, sbx, configuration, credentials, environment files, gpu passthrough, registry mirror, upstream proxy --- -Configure credentials and how Docker Sandboxes run for a project, host, or +Configure credentials and how local sandboxes run for a project, host, or network environment. These settings control sandbox creation, authentication, and connectivity. To change the tools and agent configuration inside a sandbox, see [Customize](../customize/). diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 3cd230ff4517..8ed6a3a16698 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -8,6 +8,10 @@ aliases: - /ai/sandboxes/security/credentials/ --- +These credential stores and authentication flows apply to local sandboxes. +Cloud credentials require separate setup: see +[Authenticate cloud agents](../cloud/credentials.md). + Most agents need an API key for their model provider. An HTTP/HTTPS proxy on your host intercepts outbound requests from the sandbox, looks up the matching credential on the host, and overwrites the auth header before forwarding. The diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md index baa0c22342da..0e2321fad549 100644 --- a/content/manuals/ai/sandboxes/configuration/environment-files.md +++ b/content/manuals/ai/sandboxes/configuration/environment-files.md @@ -19,7 +19,7 @@ params: text: Experimental --- -A sandbox environment file captures the setup for a project in a +A sandbox environment file captures the setup for a local sandbox in a `sbxenv.yaml` file. Share the file with project contributors so they use the same agent, tools, resources, and credentials without reproducing CLI flags and setup steps. diff --git a/content/manuals/ai/sandboxes/configuration/gpu-passthrough.md b/content/manuals/ai/sandboxes/configuration/gpu-passthrough.md index 77a6a3fde64f..48650ce76071 100644 --- a/content/manuals/ai/sandboxes/configuration/gpu-passthrough.md +++ b/content/manuals/ai/sandboxes/configuration/gpu-passthrough.md @@ -12,8 +12,8 @@ aliases: > GPU passthrough is experimental. The `--gpu` flag, the driver bundle, and the > setup steps on this page are subject to change. -Docker Sandboxes supports GPU passthrough, which allows running -workloads against a physical NVIDIA GPU. +GPU passthrough in local Docker Sandboxes runs workloads on a physical NVIDIA +GPU. GPU passthrough in Docker sandboxes works via [VFIO](https://www.kernel.org/doc/html/latest/driver-api/vfio.html), a Linux feature that assigns a PCI device directly to a virtual machine. The GPU is diff --git a/content/manuals/ai/sandboxes/configuration/registry-mirror.md b/content/manuals/ai/sandboxes/configuration/registry-mirror.md index dc4cb9dea03a..3e7c75d66151 100644 --- a/content/manuals/ai/sandboxes/configuration/registry-mirror.md +++ b/content/manuals/ai/sandboxes/configuration/registry-mirror.md @@ -6,6 +6,8 @@ keywords: docker sandboxes, sbx, registry mirror, docker hub, templates, kits, i weight: 50 --- +{{% include "sandboxes-local-scope.md" %}} + A registry mirror routes Docker Hub pulls for sandbox templates and OCI kits through your organization's registry infrastructure. If the mirror meets Docker Engine's requirements, Docker inside the sandbox uses it too. diff --git a/content/manuals/ai/sandboxes/configuration/upstream-proxy.md b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md index bb87cd3176b6..6a7c058135c9 100644 --- a/content/manuals/ai/sandboxes/configuration/upstream-proxy.md +++ b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md @@ -8,6 +8,10 @@ aliases: - /ai/sandboxes/upstream-proxy/ --- +This page describes proxy settings for local sandboxes and the local daemon. +For cloud sandbox egress controls, see +[Cloud network policy](../cloud/network-policy.md). + > [!IMPORTANT] > Upstream proxy support is experimental. Everything described on this page — > proxy URLs, PAC files, SOCKS5, use of the OS system proxy, proxy diff --git a/content/manuals/ai/sandboxes/customize/_index.md b/content/manuals/ai/sandboxes/customize/_index.md index 94e3434250a2..5f99b25e9270 100644 --- a/content/manuals/ai/sandboxes/customize/_index.md +++ b/content/manuals/ai/sandboxes/customize/_index.md @@ -15,8 +15,8 @@ params: {{< summary-bar feature_name="Docker Sandboxes sbx" >}} -Docker Sandboxes offers two ways to customize a sandbox beyond the built-in -defaults: +Docker Sandboxes offers two ways to customize a local sandbox beyond the +built-in defaults: - [Templates](templates.md) — reusable sandbox images with tools, packages, and configuration baked in. Extend a base image with a Dockerfile, or diff --git a/content/manuals/ai/sandboxes/customize/kits.md b/content/manuals/ai/sandboxes/customize/kits.md index 685f60f55292..75fe1e0d6db9 100644 --- a/content/manuals/ai/sandboxes/customize/kits.md +++ b/content/manuals/ai/sandboxes/customize/kits.md @@ -7,6 +7,9 @@ weight: 20 {{< summary-bar feature_name="Docker Sandboxes sbx" >}} +The procedures on this page use local sandboxes. For cloud template and kit +usage, see [Customize a cloud sandbox](../cloud/usage.md#customize-a-cloud-sandbox). + > [!NOTE] > Kits are experimental. The kit file format, CLI commands, and experience > for creating, loading, and managing kits are subject to change as the diff --git a/content/manuals/ai/sandboxes/customize/templates.md b/content/manuals/ai/sandboxes/customize/templates.md index 48ac92cdd566..81117d5db924 100644 --- a/content/manuals/ai/sandboxes/customize/templates.md +++ b/content/manuals/ai/sandboxes/customize/templates.md @@ -7,6 +7,9 @@ keywords: sandboxes, sbx, templates, images, dockerfile, snapshot, custom enviro {{< summary-bar feature_name="Docker Sandboxes sbx" >}} +The procedures on this page use local sandboxes. For cloud template and kit +usage, see [Customize a cloud sandbox](../cloud/usage.md#customize-a-cloud-sandbox). + Every sandbox is customizable — agents install packages, pull images, and configure tools as they work, and those changes persist for the sandbox's lifetime. Templates capture a configured environment into a reusable image diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index a451158c5c67..447443cbbacc 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -5,21 +5,25 @@ description: Frequently asked questions about Docker Sandboxes. keywords: docker sandboxes, sbx, faq, sign in, telemetry, clipboard, image paste, pricing, commercial use, allowlist, firewall, domains, proxy --- +Host integration and workspace instructions on this page describe local +sandboxes. See [Local and cloud differences](cloud/local-vs-cloud.md) before +adapting those workflows to the cloud. + ## Is Docker Sandboxes free? Can I use it commercially? -Yes to both. The `sbx` CLI is free to use, including for commercial and -professional work, with no per-seat fee. Install it, sign in with a free -Docker account, and run sandboxes at no cost. +The `sbx` CLI and local sandbox compute are free to use, including for +commercial and professional work. Cloud sandbox compute is metered through a +[Docker Agentic Platform plan](/manuals/subscription-billing/plans/docker-agentic-platform.md). +Model-provider charges are separate from sandbox compute. -The only paid component is organization governance: centrally managed network, +Organization governance for local sandboxes includes centrally managed network, filesystem, and MCP policies, [sign-in enforcement](governance/monitor-and-enforce/sign-in-enforcement.md), and [audit logs](governance/audit/). These [organization governance features](governance/) require a separate paid subscription — [contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) -to get started. Everything else, including running agents in isolated -sandboxes, is free. +to get started. ## Why do I need to sign in? @@ -41,7 +45,7 @@ Your Docker account email is only used for authentication, not marketing. ## Can I enforce sandbox policies across my organization? Yes. Admins can centrally manage network, filesystem, and MCP policies. These -controls apply to every sandbox in the organization. When organization +controls apply to local sandboxes in the organization. When organization governance is active, only organization allow rules grant access: local allow rules set with `sbx policy` are no longer evaluated, while local deny rules still apply on top. @@ -51,11 +55,15 @@ feature requires a separate paid subscription — [contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) to get started. +Organization governance is not available for cloud sandboxes in this release. +See [Cloud network policy](cloud/network-policy.md) for cloud controls. + ## Which domains do I need to allow for Docker Sandboxes to work? If your organization restricts outbound network access with a firewall or proxy, add the following domains to your allowlist so that `sbx` can -authenticate, pull images, and report diagnostics. +authenticate, pull images, and report diagnostics for local sandboxes. +Cloud operations also connect to `https://api.sandboxes-cloud.docker.com`. | Domain | Description | | -------------------------------------------------- | ----------------------- | @@ -78,10 +86,11 @@ The `sbx` CLI collects basic usage data about CLI invocations: - 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. +CLI usage telemetry does not include your prompts or code. Cloud sandboxes +execute on Docker-managed infrastructure, so files you transfer to them are +stored in the cloud. -To opt out of all analytics, set the `SBX_NO_TELEMETRY` environment variable: +To opt out of CLI usage analytics, set the `SBX_NO_TELEMETRY` environment variable: ```console $ export SBX_NO_TELEMETRY=1 @@ -144,7 +153,7 @@ in-progress task: ## Why doesn't the sandbox use my user-level agent configuration? -Sandboxes don't import your complete user-level agent configuration. Hooks, +Local sandboxes don't import your complete user-level agent configuration. Hooks, settings, and other files under directories such as `~/.claude` remain on the host. Project-level configuration in the working directory remains available inside the sandbox. @@ -162,8 +171,8 @@ to host paths because a sandboxed agent can't follow them outside the sandbox. ## Can I paste images into an agent? -Yes, but it's off by default. Text paste already works, because the terminal -sends it directly. Pasting an image or screenshot with `Ctrl+V` is different: +In local sandboxes, image paste is off by default. Text paste works because the +terminal sends it directly. Pasting an image or screenshot with `Ctrl+V` is different: the agent reads it from your host clipboard, and the sandbox blocks that access unless you opt in. @@ -191,8 +200,8 @@ $ sbx settings set clipboard.imagePaste false ## Can I use Docker Sandboxes on headless Linux? -Yes. On Linux, `sbx` stores secrets in the Secret Service exposed by your -desktop keyring, such as GNOME Keyring or KDE Wallet. Headless servers and some +Yes. For local sandboxes on Linux, `sbx` stores secrets in the Secret Service +exposed by your desktop keyring, such as GNOME Keyring or KDE Wallet. Headless servers and some WSL setups have no running Secret Service, so `sbx` falls back to a file under `$XDG_CONFIG_HOME/com.docker.sandboxes`, which defaults to `~/.config/com.docker.sandboxes` when `$XDG_CONFIG_HOME` is unset. No setup is diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 35be77907c78..059411379080 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -1,11 +1,14 @@ --- -title: Get started with Docker Sandboxes -linkTitle: Get started +title: Get started with local Docker Sandboxes +linkTitle: Get started locally weight: 20 -description: Configure agent credentials and work through your first Docker Sandboxes session. +description: Configure agent credentials and work through your first local Docker Sandboxes session. keywords: sandbox, sbx, get started, credentials, clone mode, network policy --- +This walkthrough uses local sandboxes. For cloud credentials and a first cloud +session, see [Get started with cloud sandboxes](cloud/_index.md#get-started). + 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 accessing host diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index 4db45c542720..0c9976752faa 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -5,6 +5,10 @@ description: Control what sandboxes can access, from local developer rules to or keywords: docker sandboxes, governance, policy, network access, filesystem access, mcp policy, organization policy --- +The governance described here applies to local sandboxes. Organization +governance is not available for cloud sandboxes in this release. See +[Cloud network policy](../cloud/network-policy.md) for cloud controls. + Sandbox governance covers the policy system that controls what sandboxes can access over the network, on the filesystem, and through MCP. For MCP setup and server registration, see [MCP gateway](../mcp-gateway.md). Governance operates @@ -17,7 +21,7 @@ See [Local policy](access-controls/local.md). **Organization policy** is configured centrally in Docker Home. Network and filesystem policies can also be managed via the [Governance API](/reference/api/ai-governance/). Controls defined at the org -level apply uniformly across every sandbox in the organization. Organization +level apply uniformly across every local sandbox in the organization. Organization governance can also include MCP policies for sandbox MCP activity. When organization governance is active, only organization allow rules grant access: local `sbx policy` allow rules are no longer evaluated, while local deny rules diff --git a/content/manuals/ai/sandboxes/governance/access-controls/network.md b/content/manuals/ai/sandboxes/governance/access-controls/network.md index 3085f7aa14ce..46a7486f68de 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/network.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md @@ -6,6 +6,10 @@ description: Control outbound network access from Docker Sandboxes with local an keywords: docker sandboxes, network access, network rules, governance, local policy, organization policy --- +The governance described here applies to local sandboxes. Organization +governance is not available for cloud sandboxes in this release. See +[Cloud network policy](../../cloud/network-policy.md) for cloud controls. + Network access policies control outbound connections from sandboxes. Each policy contains one or more rules that allow the domains, IP ranges, and ports a workflow needs, or block destinations that should stay unavailable. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/organization.md b/content/manuals/ai/sandboxes/governance/access-controls/organization.md index 1b65fad4edb1..47995bf4a1f2 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/organization.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/organization.md @@ -9,9 +9,13 @@ aliases: - /ai/sandboxes/governance/org/ --- +The governance described here applies to local sandboxes. Organization +governance is not available for cloud sandboxes in this release. See +[Cloud network policy](../../cloud/network-policy.md) for cloud controls. + [Local policies](local.md) give individual developers control over what their sandboxes can access. Organization policy moves that control to the admin level: -organization policies apply to sandboxes across the organization, either to +organization policies apply to local sandboxes across the organization, either to every member or to specific teams. When organization governance is active, only organization allow rules grant access: local `sbx policy` allow rules are no longer evaluated and can't expand what the organization permits. Local network diff --git a/content/manuals/ai/sandboxes/governance/audit/_index.md b/content/manuals/ai/sandboxes/governance/audit/_index.md index 844758e94453..bff10587de80 100644 --- a/content/manuals/ai/sandboxes/governance/audit/_index.md +++ b/content/manuals/ai/sandboxes/governance/audit/_index.md @@ -8,6 +8,11 @@ keywords: docker sandboxes, audit log, audit logging, AI Governance, policy deci {{< summary-bar feature_name="AI Governance Audit Logs" >}} +The Docker Sandboxes coverage on this page applies to local sandboxes. +Docker Cloud delivery stores their audit records in the cloud; it does not add +cloud sandbox coverage. For cloud network decisions, see +[Cloud policy logs](../../cloud/network-policy.md#inspect-network-policy). + AI Governance Audit Logs record Docker AI Governance activity for your organization. Each record captures the principal, action, target, decision, and time for a governance event. Records contain metadata only. They don't contain diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index ed96c722a219..6d13614f18b6 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -5,6 +5,10 @@ description: The resource model, rule syntax, and evaluation logic behind Docker keywords: docker sandboxes, policy concepts, rule syntax, network rules, filesystem rules, mcp policy, cedar policy, precedence, rule evaluation --- +The governance described here applies to local sandboxes. Organization +governance is not available for cloud sandboxes in this release. See +[Cloud network policy](../cloud/network-policy.md) for cloud controls. + ## Resource model Docker sandbox governance is built around two resource types: **policies** and diff --git a/content/manuals/ai/sandboxes/install.md b/content/manuals/ai/sandboxes/install.md index 9d7b0397573b..edef297ffef9 100644 --- a/content/manuals/ai/sandboxes/install.md +++ b/content/manuals/ai/sandboxes/install.md @@ -6,11 +6,16 @@ description: Install the sbx CLI on macOS, Windows, or Linux and sign in to Dock keywords: sandbox, sbx, install, macOS, Windows, Linux, Ubuntu --- -Install the `sbx` CLI to run AI coding agents in isolated microVMs. You don't -need Docker Desktop or Docker Engine to use `sbx`. +Install the `sbx` CLI to run AI coding agents in local or cloud sandboxes. You +don't need Docker Desktop or Docker Engine to use `sbx`. Cloud sandboxes require +version 0.42.0 or later. ## Prerequisites +The operating system and processor requirements apply to the CLI installation. +Hypervisor and KVM setup is required only to run local sandboxes. For cloud +account requirements, see [Cloud sandboxes](cloud/_index.md#prerequisites). + ### macOS - macOS Sonoma version 14 or later @@ -20,10 +25,10 @@ need Docker Desktop or Docker Engine to use `sbx`. - Windows 11 - A 64-bit Intel or AMD processor -- Windows Hypervisor Platform +- Windows Hypervisor Platform for local sandboxes -To turn on Windows Hypervisor Platform, open an elevated PowerShell prompt and -run: +To run local sandboxes, open an elevated PowerShell prompt and turn on Windows +Hypervisor Platform: ```powershell Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All @@ -33,21 +38,22 @@ Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All - Ubuntu 24.04 or later - A 64-bit Intel or AMD processor, or a 64-bit Arm processor -- KVM hardware virtualization supported and turned on by the CPU -- Your user account in the `kvm` group +- For local sandboxes, KVM hardware virtualization supported and turned on by + the CPU, and your user account in the `kvm` group -If you're running inside a virtual machine or virtual desktop infrastructure -environment, the environment must support nested virtualization. +To run local sandboxes inside a virtual machine or virtual desktop +infrastructure environment, the environment must support nested virtualization. +Cloud sandboxes don't require this setup. -Verify that KVM is available: +For local sandboxes, verify that KVM is available: ```console $ lsmod | grep kvm ``` A working setup shows `kvm_intel`, `kvm_amd`, `kvm_arm64`, or `kvm` in the -output. If the output is empty, run `kvm-ok` for diagnostics. `sbx` requires -KVM to start. +output. If the output is empty, run `kvm-ok` for diagnostics. The local sandbox +runtime requires KVM to start. Add your user to the `kvm` group: @@ -144,4 +150,5 @@ $ sbx login The command opens a browser for Docker OAuth. See the [FAQ](faq.md) for why sign-in is required and how Docker handles your data. -After signing in, [run your first sandbox](get-started.md). +After signing in, [run your first local sandbox](get-started.md) or +[get started with cloud sandboxes](cloud/_index.md#get-started). diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md index 6892b889846a..2015b577a6ce 100644 --- a/content/manuals/ai/sandboxes/integrations/_index.md +++ b/content/manuals/ai/sandboxes/integrations/_index.md @@ -8,6 +8,10 @@ keywords: docker sandboxes, ssh, integrations, vs code, cursor, remote developme {{< summary-bar feature_name="Docker Sandboxes SSH" >}} +These integrations use local sandbox SSH access. Cloud sandboxes use a +different SSH configuration and address: see +[Connect with SSH](../cloud/usage.md#connect-with-ssh). + You can connect an external editor or desktop app to a running sandbox over SSH. This lets you use the tools you already know — VS Code, Cursor, Claude Desktop, and others — while your code runs, builds, and executes inside the diff --git a/content/manuals/ai/sandboxes/integrations/chatgpt.md b/content/manuals/ai/sandboxes/integrations/chatgpt.md index 134a0f70d6ec..b5be5e52bc6b 100644 --- a/content/manuals/ai/sandboxes/integrations/chatgpt.md +++ b/content/manuals/ai/sandboxes/integrations/chatgpt.md @@ -8,6 +8,9 @@ keywords: docker sandboxes, chatgpt, codex, openai, remote ssh, sbx {{< summary-bar feature_name="Docker Sandboxes SSH" >}} +These connection instructions use a local sandbox. For cloud SSH setup, see +[Connect with SSH](../cloud/usage.md#connect-with-ssh). + Connect the ChatGPT desktop app to a sandbox over SSH so Codex works inside the isolated environment instead of on your host. diff --git a/content/manuals/ai/sandboxes/integrations/claude-desktop.md b/content/manuals/ai/sandboxes/integrations/claude-desktop.md index 26017d71942f..50f2778646c1 100644 --- a/content/manuals/ai/sandboxes/integrations/claude-desktop.md +++ b/content/manuals/ai/sandboxes/integrations/claude-desktop.md @@ -8,6 +8,9 @@ keywords: docker sandboxes, claude desktop, claude code, remote ssh, sbx {{< summary-bar feature_name="Docker Sandboxes SSH" >}} +These connection instructions use a local sandbox. For cloud SSH setup, see +[Connect with SSH](../cloud/usage.md#connect-with-ssh). + Claude Desktop can run Claude Code on a remote machine over SSH. Point it at a sandbox so the agent works inside the isolated environment instead of on your host. diff --git a/content/manuals/ai/sandboxes/integrations/cursor.md b/content/manuals/ai/sandboxes/integrations/cursor.md index 13024801ba69..6ec238168806 100644 --- a/content/manuals/ai/sandboxes/integrations/cursor.md +++ b/content/manuals/ai/sandboxes/integrations/cursor.md @@ -8,6 +8,9 @@ keywords: docker sandboxes, cursor, remote ssh, remote development, sbx {{< summary-bar feature_name="Docker Sandboxes SSH" >}} +These connection instructions use a local sandbox. For cloud SSH setup, see +[Connect with SSH](../cloud/usage.md#connect-with-ssh). + Cursor is built on VS Code, so it connects to a sandbox the same way, using Remote - SSH. Your editor stays on your host while files, terminals, and extensions run in the isolated sandbox. diff --git a/content/manuals/ai/sandboxes/integrations/t3-code.md b/content/manuals/ai/sandboxes/integrations/t3-code.md index fe7ddffb575b..79281a4593cc 100644 --- a/content/manuals/ai/sandboxes/integrations/t3-code.md +++ b/content/manuals/ai/sandboxes/integrations/t3-code.md @@ -8,6 +8,9 @@ keywords: docker sandboxes, t3 code, remote ssh, remote development, sbx {{< summary-bar feature_name="Docker Sandboxes SSH" >}} +These connection instructions use a local sandbox. For cloud SSH setup, see +[Connect with SSH](../cloud/usage.md#connect-with-ssh). + T3 Code's SSH integration lets the desktop app drive coding agents inside a sandbox. T3 Code has no dedicated Docker Sandboxes integration — it treats the sandbox as an ordinary SSH host, connects to it, and starts a T3 server inside diff --git a/content/manuals/ai/sandboxes/integrations/vscode.md b/content/manuals/ai/sandboxes/integrations/vscode.md index 3e82d46c674c..28dcd329a352 100644 --- a/content/manuals/ai/sandboxes/integrations/vscode.md +++ b/content/manuals/ai/sandboxes/integrations/vscode.md @@ -8,6 +8,9 @@ keywords: docker sandboxes, vs code, remote ssh, remote development, sbx {{< summary-bar feature_name="Docker Sandboxes SSH" >}} +These connection instructions use a local sandbox. For cloud SSH setup, see +[Connect with SSH](../cloud/usage.md#connect-with-ssh). + Use the Remote - SSH extension to open a VS Code window that runs inside a sandbox. Your editor stays on your host while files, terminals, and extensions run in the isolated sandbox. diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md index fbcdbd5b3bd1..bb50fc9a339c 100644 --- a/content/manuals/ai/sandboxes/mcp-gateway.md +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -5,6 +5,10 @@ keywords: docker sandboxes, sbx, MCP gateway, Model Context Protocol, MCP server weight: 80 --- +This page describes the local MCP gateway. Cloud sandboxes use MCP servers +configured in Docker Agentic Platform: see +[Load an MCP server](cloud/usage.md#load-an-mcp-server). + Docker Sandboxes includes an MCP gateway for connecting agents to Model Context Protocol servers. The gateway gives the agent inside the sandbox one MCP endpoint, while `sbx` manages the registered servers, OAuth credentials, and diff --git a/content/manuals/ai/sandboxes/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md index 0d4f522ba859..0c175bc7b979 100644 --- a/content/manuals/ai/sandboxes/security/_index.md +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -6,6 +6,8 @@ description: Trust boundaries, isolation layers, and security properties of Dock keywords: docker sandboxes, security model, isolation, trust boundaries, microVM --- +{{% include "sandboxes-local-scope.md" %}} + Docker Sandboxes run AI agents in microVMs so they can execute code, install packages, and use tools without accessing host resources beyond those you share. Multiple isolation layers protect your host system. diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index c19ba2e1c02c..538dcafdbc5c 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -6,6 +6,8 @@ description: What a sandbox permits and blocks before you change any settings. keywords: docker sandboxes, security defaults, network policy, credentials, shared skills, sbx --- +{{% include "sandboxes-local-scope.md" %}} + A sandbox created with `sbx run claude` and no additional flags has the following security posture. diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index f19ff970f451..384e0af86da3 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -7,6 +7,8 @@ aliases: - /ai/sandboxes/security/workspace/ --- +{{% include "sandboxes-local-scope.md" %}} + AI coding agents need to execute code, install packages, and run tools on your behalf. Docker Sandboxes run each agent in its own microVM. Five isolation layers protect your host: hypervisor, network, Docker Engine, diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 0ecaa572e67d..d8628a090b0d 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -5,6 +5,11 @@ description: Resolve common issues when using Docker Sandboxes. keywords: docker sandboxes, sbx, troubleshooting, diagnostics, reset, network policy, git, ssh --- +These diagnostics and recovery steps apply to local sandboxes. For cloud +authentication, files, expiration, and network access, see +[Cloud sandboxes](cloud/). Local daemon restarts and `sbx reset` do not repair +cloud sandbox state. + ## Run diagnostics Before digging into a specific issue, run diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index da85d47b075e..10068572ab6d 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -5,6 +5,9 @@ description: Basic sbx commands for creating, managing, and connecting to Docker keywords: docker sandboxes, sbx, usage, run, create, stop, remove, ports, workspaces --- +This page describes local sandboxes. For cloud commands, file transfers, ports, +and expiration, see [Use cloud sandboxes](cloud/usage.md). + Use this page as a command-oriented guide to day-to-day `sbx` operations. For scenario-based recommendations, see [Workflow patterns](workflows/). diff --git a/content/manuals/ai/sandboxes/workflows/_index.md b/content/manuals/ai/sandboxes/workflows/_index.md index 005d3b323048..7a70ff7774cb 100644 --- a/content/manuals/ai/sandboxes/workflows/_index.md +++ b/content/manuals/ai/sandboxes/workflows/_index.md @@ -8,7 +8,7 @@ toc_max: 2 --- Choose a workflow based on how you want to develop, authenticate tools, or run -sandboxes in automation. For command syntax and lifecycle basics, see +local sandboxes in automation. For command syntax and lifecycle basics, see [Usage](../usage.md). ## Choose how code moves diff --git a/content/manuals/ai/sandboxes/workflows/agent-skills.md b/content/manuals/ai/sandboxes/workflows/agent-skills.md index ad9d751ca5c8..fe430af769d0 100644 --- a/content/manuals/ai/sandboxes/workflows/agent-skills.md +++ b/content/manuals/ai/sandboxes/workflows/agent-skills.md @@ -7,9 +7,9 @@ keywords: docker sandboxes, sbx, agent skills, shared skills, git repository, cl --- Shared agent skills let you install skills from Git repositories or import -skills from supported agents on your host. `sbx` keeps installed skills in a -persistent store that survives sandbox deletion and is shared by default with -new sandboxes that run a supported agent. +skills from supported agents on your host for use in local sandboxes. `sbx` +keeps installed skills in a persistent store that survives sandbox deletion +and is shared by default with new sandboxes that run a supported agent. > [!NOTE] > Shared agent skills are experimental. diff --git a/content/manuals/ai/sandboxes/workflows/authentication.md b/content/manuals/ai/sandboxes/workflows/authentication.md index 0edd3012888f..4ee5470b8de0 100644 --- a/content/manuals/ai/sandboxes/workflows/authentication.md +++ b/content/manuals/ai/sandboxes/workflows/authentication.md @@ -6,6 +6,9 @@ description: Use authenticated command-line tools and dynamic secret sources ins keywords: docker sandboxes, sbx, authentication, github cli, registry, 1password, aws secrets manager --- +These workflows resolve credentials on the host for local sandboxes. For +cloud secret setup, see [Authenticate cloud agents](../cloud/credentials.md). + The sandbox proxy handles API credentials for model providers automatically, but agents often also need credentials for tools like `gh`, `docker`, or a secrets manager. Configure the credential source on your host, and the proxy diff --git a/content/manuals/ai/sandboxes/workflows/automation.md b/content/manuals/ai/sandboxes/workflows/automation.md index fe2126e6e4df..16257cf1d1ee 100644 --- a/content/manuals/ai/sandboxes/workflows/automation.md +++ b/content/manuals/ai/sandboxes/workflows/automation.md @@ -6,6 +6,9 @@ description: Authenticate and run Docker Sandboxes in CI systems and other headl keywords: docker sandboxes, sbx, ci, headless, automation, personal access token --- +This page describes local sandboxes in CI. For cloud execution without local +virtualization, see [Run without attaching](../cloud/usage.md#run-without-attaching). + For CI environments and scripts where a browser isn't available, authenticate with a Docker Personal Access Token (PAT): diff --git a/content/manuals/ai/sandboxes/workflows/development.md b/content/manuals/ai/sandboxes/workflows/development.md index 6cf8e6f3f129..fbb936a4d6c8 100644 --- a/content/manuals/ai/sandboxes/workflows/development.md +++ b/content/manuals/ai/sandboxes/workflows/development.md @@ -6,6 +6,9 @@ description: Build, test, and connect to development services in Docker Sandboxe keywords: docker sandboxes, sbx, local development, build, test, ports, host services --- +This page describes local sandboxes, host services, and local port mappings. +For cloud endpoints, see [Expose a port](../cloud/usage.md#expose-a-port). + Use a sandbox's private runtime to build images, run tests, and connect local tools to development services across the sandbox boundary. diff --git a/content/manuals/ai/sandboxes/workflows/git.md b/content/manuals/ai/sandboxes/workflows/git.md index 0d8f555a4c73..54c9cf9191c9 100644 --- a/content/manuals/ai/sandboxes/workflows/git.md +++ b/content/manuals/ai/sandboxes/workflows/git.md @@ -6,6 +6,12 @@ description: Choose a Git workspace mode and manage branches, parallel tasks, an keywords: docker sandboxes, sbx, git, clone mode, direct mode, worktrees, branches, commit signing --- +These workspace modes apply to local sandboxes. In cloud sandboxes, +[transfer files or clone a remote repository](../cloud/usage.md#transfer-files). +To copy a sandbox filesystem between environments, see +[Move a sandbox](../cloud/move.md). Host mounts and clone-mode volumes are not +included in that snapshot. + Sandboxes support three approaches for working with Git repositories. The right choice depends on whether you want branch isolation and whether you plan to run tasks in parallel: