docs: cloud sandboxes CLI (#26158)

## Description Add cloud Sandboxes documentation for sbx v0.45.0, covering credentials, network policy, lifecycle, environment files, and transfers between local and cloud sandboxes. Document named sandbox reuse and resume, resource sizes and platform selection, custom secrets, move behavior, and local UDP guidance. Link to the canonical Docker Agentic Platform signup, billing, and Console MCP instructions. Keep CLI sign-in, access checks, and cloud credential setup in the Sandboxes guides. This PR also vendors the CLI reference including `sbx move`, and aligns timeout and move guidance with it. Kits v3 and API/SDK documentation are handled separately. Validation: scoped Markdown and Vale checks and a full Hugo build passed. Cloud and Agentic Platform guides passed rendered internal link and anchor checks, including the canonical signup page's discovery. The earlier CLI import verified all 119 vendored files against upstream byte-for-byte and checked 1,083 rendered CLI-reference links and anchors. Behavior was checked against source; live cloud workflows and checkout were not exercised. @netlify /ai/sandboxes/cloud/ Generated by Codex
2026-11-04 10:01:00 +00:00 · 2026-09-24 18:13:01 +02:00
1 parent bed22bda81
commit 3de2f99327
@@ -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

@@ -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).
@@ -51,8 +51,11 @@ Docker Agentic Platform lets you run agents and tools in isolated cloud
 sandboxes. Your agent keeps working when you close the Console, disconnect
 your computer, or put it to sleep.

-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).

 In the Console, choose a [kit](/manuals/agentic-platform/kits.md) and configure
 the sandbox's credentials, network access, tools, and compute size. Once it
@@ -26,15 +26,19 @@ To access private GitHub repositories from inside a sandbox, use a

 ## How does Docker Agentic Platform differ from Docker Sandboxes?

-With Docker Agentic Platform, you run sandboxes in the cloud and manage their
-compute, MCP connections, secrets, and network policies in a web Console. For
-local development, Docker Sandboxes runs on your machine through the `sbx`
-command.
+Docker Agentic Platform runs sandboxes on Docker-managed cloud infrastructure
+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. The initial release doesn't support moving a running sandbox or its local
-bind mounts from your machine to the cloud.
+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?

@@ -68,7 +68,7 @@ base image and keep the kit's bundled files small.

 To ask your coding agent to help create a kit, copy the prompt from **Kits** and
 paste it into your agent. Follow the **Kit authoring docs** link for instructions,
-or see [Kit authoring](/manuals/ai/sandboxes/customize/kits.md).
+or see [Kit authoring](/manuals/ai/sandboxes/customize/author/_index.md).

 After publishing the kit to a public registry, enter its reference in the
 launcher. Its base image must also be public.
@@ -41,10 +41,11 @@ supported method; they can also be used by Docker Agent and agents running in
 Docker Sandboxes. Browse the [Docker Skills
 catalog](https://github.com/docker/skills#readme) for current guidance.

-**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.

 Docker Agentic Platform is an experimental service for running agents in
 Docker-managed cloud sandboxes. Its web Console provides kit selection,
@@ -8,40 +8,42 @@ 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 uses a
+[pay-as-you-go subscription](/manuals/agentic-platform/signup.md#billing).
+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.

 To create and manage cloud sandboxes from your application, see
 [Sandboxes API and SDK](../sandboxes-api/_index.md).

 ## 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
@@ -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/)
@@ -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
@@ -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.

@@ -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.

@@ -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.

@@ -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
@@ -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
@@ -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.

@@ -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.

@@ -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.

@@ -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.

@@ -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
@@ -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).

@@ -0,0 +1,134 @@
+---
+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
+params:
+  sidebar:
+    badge:
+      color: violet
+      text: Experimental
+---
+
+> [!NOTE]
+> Cloud sandbox support in the `sbx` CLI is experimental. Features and behavior
+> may change.
+
+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.45.0 or later
+- An active [Docker Agentic Platform subscription](/manuals/agentic-platform/signup.md#activate-cloud-access)
+
+Follow [Signup and billing](/manuals/agentic-platform/signup.md) to activate
+cloud access and review compute charges. Then return here to sign in from the
+CLI and configure your agent.
+
+### Sign in from the CLI
+
+Sign in with the same Docker account you used to subscribe:
+
+```console
+$ sbx login
+```
+
+Check cloud connectivity and account access:
+
+```console
+$ sbx --cloud diagnose
+```
+
+If the check reports that your account doesn't have access, follow
+[Check account access](/manuals/agentic-platform/signup.md#check-account-access).
+
+## 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
+```
+
+See [Authenticate cloud agents](credentials.md) for other agents and credential
+options.
+
+Cloud sandboxes expire after one hour by default. On expiration, the service
+stops sandboxes that can be resumed and deletes the rest. Check the timeout
+action before relying on a sandbox to retain your work. 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
+
+- [Signup and billing](/manuals/agentic-platform/signup.md) covers activation
+  and compute charges
+- [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 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
@@ -0,0 +1,151 @@
+---
+title: Authenticate cloud agents
+linkTitle: Credentials
+description: Configure cloud-specific API keys and OpenAI 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. Configure a cloud credential using one of the following methods before
+starting a cloud sandbox.
+
+## Choose an authentication method
+
+For Claude Code, use an Anthropic API key. For Codex, use an OpenAI API key or
+account-scoped OpenAI OAuth credentials.
+
+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 <service>` | 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 an 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` | API key |
+| `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` | Use a [custom secret](#configure-a-custom-secret) |
+| `xai` | API key |
+
+To configure a supported service, run `sbx --cloud secret set <service>`.
+For OpenAI OAuth, add `--oauth` and use account scope.
+
+For other services, configure a [custom secret](#configure-a-custom-secret).
+
+The cloud secret commands don't support registry credentials or dynamic
+`--ref` and `--command` resolvers. An
+[environment file](../configuration/environment-files.md#secrets) can resolve a
+host command or vault reference once with `snapshot: true` and upload the
+result as a literal cloud secret.
+
+## Configure a custom secret
+
+Use `set-custom` for an API that isn't a built-in service:
+
+```console
+$ sbx --cloud secret set-custom --name project-api \
+    --host api.example.com --env PROJECT_API_TOKEN
+```
+
+The command prompts for the value. Sandboxes using this secret receive a
+placeholder in `PROJECT_API_TOKEN`. The cloud proxy sets
+`Authorization: Bearer <secret>` on requests to `api.example.com`. Unlike local
+custom secrets, cloud injection sets the header based on the destination host
+without requiring a matching placeholder in the request.
+
+Use `--header` to select another header. When you specify a header, the default
+value is the raw secret. Use `--format` with one `%s` placeholder to add a
+prefix, for example `--header Authorization --format 'Bearer %s'`.
+
+Each `--host` must be an exact DNS name without a scheme, port, or path. Repeat
+the flag for multiple hosts. IP addresses and wildcards aren't supported.
+Add `--sandbox cloud-project` to scope the secret to that sandbox, and set it
+before creating the sandbox. A custom secret name can't match a built-in
+service name.
+
+## 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
+$ sbx --cloud secret rm project-api
+```
+
+Custom secrets can also be removed by a host they serve, using
+`sbx --cloud secret rm --host api.example.com`. Removal asks for confirmation.
+Use `--force` in scripts. Cloud mode doesn't support removing every secret in
+one operation.
@@ -0,0 +1,105 @@
+---
+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 |
+| CPU architecture | Uses the platform supported by the local runtime | Supports `linux/amd64` and `linux/arm64`, subject to account availability; moves must retain the source platform |
+| 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; local policies aren't copied |
+| MCP servers | Uses servers registered in the local MCP store | Uses servers connected through Docker Agentic Platform |
+| 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 | [Pay-as-you-go compute](/manuals/agentic-platform/signup.md#billing) |
+
+If your workflow runs Docker inside the sandbox, review the
+[Docker exec and healthcheck limitation](usage.md#docker-exec-and-healthchecks).
+It can affect container setup, debugging, and Compose service readiness.
+
+## 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
+- Model selection through `--model` and `--provider`
+- Host port bindings
+- Host-backed agent skills and the full local MCP management workflow
+
+The CLI rejects local-only flags used with `--cloud` instead of ignoring them.
+
+You can use [environment files](../configuration/environment-files.md#use-a-cloud-environment)
+with `sbx --cloud env`. Cloud environments support a subset of the local
+configuration fields, including agents, environment variables, resource limits,
+and credentials. Remove host workspace and port mappings before using a local
+environment file in the cloud.
+
+## 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 or managed secrets. Credentials saved in copied files can
+still travel with the sandbox.
+
+## Network policy differences
+
+Configure and verify [cloud network policy](network-policy.md) separately.
+Moving a sandbox doesn't carry its local policy configuration into the cloud.
+The cloud CLI supports account and sandbox network rules, but rejects local
+governance profiles and the `--protocol` option.
+
+HTTP method and path restrictions, also called L7 filtering, aren't supported
+in cloud sandboxes. If these rules apply to a local sandbox, `sbx move` warns
+and asks for confirmation before moving it to the cloud.
+
+## What changes when you move
+
+[`sbx move`](move.md) copies a filesystem snapshot and creates a separate
+destination sandbox. It doesn't transfer running processes or memory, and it
+leaves the source sandbox in place. Large images can take time to upload or
+download, depending on image size and available bandwidth. For cloud-to-local
+moves, also allow for [temporary disk space](move.md#move-from-cloud-to-local).
+
+| State | Local to cloud | Cloud to local | What to do |
+| --- | --- | --- | --- |
+| Network policy | Local rules aren't copied; the CLI warns that cloud policy applies | Cloud rules aren't copied; the CLI notice explains that the host's default egress policy applies | Configure destination rules and verify allowed and blocked connections before continuing work |
+| Managed secrets | Uses applicable credentials in the cloud secret store | Uses applicable credentials in the local secret store | Configure credentials in the destination store; the CLI warns that secrets aren't copied and you may need to sign in again |
+| Workspace and attached storage | Host mounts and clone-mode volumes aren't copied; a workspace triggers a warning and confirmation | Cloud volumes aren't copied and no host folder is mounted | Transfer needed files separately with `sbx cp` |
+| Published ports | TCP ports get cloud URLs; refused ports are skipped with a warning | Ports use local loopback bindings; cloud URLs aren't retained | Inspect destination ports and update clients |
+| CPU and memory | Rounds recorded source limits up to a supported cloud size; missing limits use defaults with a warning | Uses local defaults | Check destination resources and workload performance; `sbx move` has no CPU or memory override flags |
+| CPU architecture | Cloud access must support the source platform | The local runtime must support the source platform | Match platforms; the CLI checks compatibility before transfer |
+
+The managed-secret warning doesn't itself block a move. Configure
+[cloud credentials](credentials.md) or
+[local credentials](../configuration/credentials.md) before using an agent
+that needs them. Credentials written to files inside the sandbox can be
+included in the snapshot; remove those files before moving if you don't want
+the credentials copied.
+
+Cloud-to-local moves display a notice and ask for confirmation. Local-to-cloud
+moves ask for confirmation when workspace files or L7 filtering would be left
+behind. If a confirmation is required and standard input isn't a terminal,
+the move fails unless you pass `--force`. This flag skips confirmation but
+retains warnings and doesn't change what transfers.
+
+Verify the destination's files, credentials, network access, ports, and
+[expiration settings](usage.md#configure-expiration) before removing the source.
@@ -0,0 +1,150 @@
+---
+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.
+The move can return before the stop finishes. Check `sbx --cloud ls` for its
+state. A cloud source with no agent is left running.
+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 `--platform linux/amd64` or `--platform linux/arm64`
+to match your local sandbox runtime. The CLI checks compatibility before
+transferring the snapshot.
+
+## 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 prefix. The cloud destination appends
+a short unique suffix:
+
+```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 uses cloud network policy. Local network rules don't transfer.
+If the local source has HTTP method or path restrictions, the CLI warns and
+asks for confirmation because those restrictions won't apply in the cloud.
+`--force` skips the prompt but retains the warning.
+
+Published TCP sandbox ports are published on the cloud destination with cloud
+URLs. Ports that the cloud refuses are skipped with a warning. 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.
+
+The CLI rounds the source's recorded CPU and memory limits up to a supported
+[cloud size](usage.md#choose-resources-and-platform). Missing limits use cloud
+defaults with a warning. Limits above the largest cloud size prevent the move.
+The `move` command has no `--cpus` or `--memory` overrides. Resource sizing
+doesn't guarantee the same performance as the source; check your workload on
+the destination before removing the source.
+
+### Set destination expiration
+
+The cloud destination has an expiration time, even if the local source had
+none. Without `--ttl`, it uses the server default, typically one hour. The
+move requests that the sandbox stop on expiration when the account and sandbox
+support it. Otherwise, it falls back to the server's default timeout action,
+which deletes the sandbox.
+
+Set the expiration and action explicitly when moving work you want to retain:
+
+```console
+$ sbx move local-project --to cloud --ttl 2h --on-timeout stop
+```
+
+The `stop` action preserves state. An explicit request fails if stopping is
+unavailable. Use `--on-timeout delete` to delete on expiration.
+These flags apply only to moves to the cloud. After the move, inspect or extend
+the expiration with [`sbx --cloud ttl`](usage.md#configure-expiration).
+
+## 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.
+
+Published TCP ports are saved on the local sandbox and bound to loopback while
+it runs. Host port numbers can change after a restart. Run
+`sbx ports local-copy` to see the bindings.
+
+The move doesn't create a host workspace. Use `sbx cp` to copy files from the
+local sandbox to your host. Attached cloud volumes and environment variables
+don't transfer. The local destination uses local CPU and memory defaults.
+
+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`.
+
+Layer reuse during download can require up to 32 GiB of temporary host disk
+space in addition to the local runtime's image storage.
+
+## 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.
@@ -0,0 +1,126 @@
+---
+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]
+>
+> Local policy configuration isn't copied to cloud sandboxes. 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.
+
+Cloud creation uses cloud account policy, network rules passed to the command,
+and network access declared by the agent or kit. Both `sbx --cloud create` and
+`sbx --cloud run` leave local network and organization policies on the host.
+Moving a local sandbox to the cloud also uses cloud policy.
+
+Define the intended policy in the cloud store. After creation, inspect the
+configured rules and [verify connection decisions](#inspect-network-policy).
+
+## Initialize account policy
+
+Set the account policy to `allow-all`, `balanced`, or `deny-all`:
+
+```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.
+
+The `balanced` preset sets deny-all as the default and adds allow rules for
+common development services. To set a default for one sandbox, use
+`sbx --cloud policy init deny-all --sandbox cloud-project`.
+
+You can run `init` again to change the default. Existing allow and deny rules
+remain in place. Use `reset` to remove account rules before choosing another
+preset.
+
+## 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.
+
+Cloud rules match network destinations. HTTP method and path restrictions,
+`--protocol`, and local governance profiles aren't supported.
+
+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
+
+Remove a rule by its pattern, from whichever allow or deny list contains it:
+
+```console
+$ sbx --cloud policy rm network --resource api.github.com:443
+$ sbx --cloud policy rm network --sandbox cloud-project --resource api.anthropic.com:443
+```
+
+Remove the custom account policy and return to the platform default:
+
+```console
+$ sbx --cloud policy reset
+```
+
+The command asks for confirmation and prints the default stored by the server
+after the reset. Use `--force` in scripts. The local daemon is unaffected.
+Sandbox-specific policies remain in place and can still grant access. Inspect
+those policies separately.
@@ -0,0 +1,355 @@
+---
+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. On expiration, the service
+stops sandboxes that can be resumed and deletes the rest. See
+[Configure expiration](#configure-expiration) to choose the timeout and 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, or reuse the named sandbox if it
+already exists:
+
+```console
+$ sbx --cloud run claude --name cloud-project
+```
+
+Without `--name`, an interactive run offers existing sandboxes for that agent
+and an option to create another. Pass `--new` to create a fresh sandbox.
+Launches that bake a kit template also create a fresh sandbox.
+
+Reusing a sandbox keeps its creation settings. Flags such as `--cpus`,
+`--memory`, `--platform`, `--ttl`, `--env`, and `--allow-network` are rejected
+when resuming. Use `--new` to create a sandbox with different settings.
+
+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
+```
+
+Cloud sandbox names must have at least two characters, start with a letter or
+number, and contain only letters, numbers, and hyphens. The name `default` is
+reserved. Periods accepted in local sandbox names aren't accepted in the cloud.
+
+Cloud creation doesn't accept workspace paths. For example,
+`sbx --cloud run claude .` returns an error because `.` refers to the local
+filesystem.
+
+### Choose resources and platform
+
+Without resource flags, a cloud sandbox starts with 2 CPUs and 4 GiB of
+memory. Use `--cpus` and `--memory` to select one of these configurations:
+
+| Size | CPUs | Memory |
+| --- | --- | --- |
+| micro | 1 | 2 GiB |
+| small | 2 | 4 GiB |
+| medium | 4 | 8 GiB |
+| large | 8 | 16 GiB |
+| xl | 16 | 32 GiB |
+
+For example:
+
+```console
+$ sbx --cloud create --name cloud-project --cpus 4 --memory 8g claude
+```
+
+If you specify only CPU or memory, the CLI selects the matching value for the
+other resource. Unsupported combinations are rejected.
+
+Use `--platform linux/amd64` or `--platform linux/arm64` to select an
+architecture supported by your account. This matters when you plan to
+[move the sandbox to your machine](move.md): the architectures must match.
+
+## Run without attaching
+
+For scripts or terminals without interactive input, start the sandbox without
+opening an agent session:
+
+```console
+$ sbx --cloud run --detached claude --name cloud-task
+```
+
+A detached run with `--name` reuses the named sandbox and starts it if stopped.
+If the sandbox doesn't exist, or you omit `--name`, it creates a sandbox.
+Use `sbx --cloud exec` to run commands and `sbx --cloud rm --force` for
+unattended cleanup. An interactive agent session requires `run` or `attach`
+from a terminal.
+
+To detach from an interactive `run` or `attach` session while leaving the
+agent running, press `Ctrl+\`. Reconnect with `sbx --cloud attach <sandbox-name>`.
+Reconnecting joins the existing agent session. Use `--detach-keys` with `run`
+or `attach` to change the detach gesture, for example `--detach-keys ctrl-x,ctrl-d`.
+
+## 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 <sandbox-id>@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 a sandbox port number with an optional `/tcp` suffix, such
+as `8080/tcp`. Host IP addresses, host port bindings, and other protocols are
+rejected.
+
+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. If you omit `--on-timeout`, the server
+stops sandboxes that can be resumed and deletes the rest. Choose an action
+explicitly when you need a particular outcome:
+
+- `stop` preserves the sandbox so it can be started again. This requires
+  support for stopping the sandbox.
+- `restart` stops and immediately starts the sandbox. If you also specify
+  `--ttl`, it must be at least one hour.
+- `delete` removes the sandbox.
+
+Volume-backed sandboxes require the `delete` action. Omitting `--ttl` uses
+the server default. Setting `--ttl 0` is an error, not a way to disable
+expiration.
+
+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 while preserving its memory and filesystem:
+
+```console
+$ sbx --cloud stop cloud-project
+```
+
+The command returns when the stop request is accepted. Check `sbx --cloud ls`
+to confirm that the sandbox has stopped. Compute isn't billed while it is
+stopped.
+
+To resume the sandbox and connect to its agent:
+
+```console
+$ sbx --cloud attach cloud-project
+```
+
+You can also use `sbx --cloud run claude --name cloud-project`, or run the agent
+without `--name` and select the sandbox when prompted. Add `--detached` to a
+named run to resume without attaching.
+
+Resuming keeps the sandbox ID and state. Check its expiration with
+`sbx --cloud ttl cloud-project` after resuming.
+
+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 asks for confirmation, deletes the cloud sandbox, and can't be undone.
+Use `--force` to skip the prompt in scripts.
+
+## 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. See
+[Kits](../customize/_index.md) for customization and
+[Local and cloud differences](local-vs-cloud.md) for host-dependent features.
+Configure [cloud credentials](credentials.md) before adapting a local kit.
+
+To declare reusable cloud configuration in a file, see
+[Use a cloud environment](../configuration/environment-files.md#use-a-cloud-environment).
+
+## Load an MCP server
+
+[Connect an MCP server in Docker Agentic Platform](/manuals/agentic-platform/mcp.md)
+before loading it into a cloud sandbox. Use the same Docker account you use
+with `sbx`.
+
+Load the connected server into a running cloud sandbox, using its name from
+the console:
+
+```console
+$ sbx --cloud mcp load <server-name> --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`.
+
+List servers reported by existing cloud sandbox gateways, or inspect one
+sandbox's gateway:
+
+```console
+$ sbx --cloud mcp ls
+$ sbx --cloud mcp ls cloud-project
+```
+
+The account listing shows servers reported by gateways, with the sandboxes
+that use them. It omits unused server configurations and servers skipped by
+a gateway. The sandbox view includes skipped servers.
+
+## Diagnose cloud access
+
+Check the CLI, Docker sign-in, cloud API connectivity, and account access:
+
+```console
+$ sbx --cloud diagnose
+```
+
+These checks don't require a local sandbox daemon. For local diagnostics,
+see [Troubleshooting](../troubleshooting.md).
+
+## Known limitations
+
+### Docker exec and healthchecks
+
+When running Docker inside a cloud sandbox, `docker exec` can access the
+sandbox VM filesystem instead of the target container's filesystem. This also
+affects `docker compose exec` and Docker healthchecks, which use the same
+execution path.
+
+Commands can fail because application files, binaries, or mounted data aren't
+found. They can also succeed while reading or writing the wrong files. A
+successful exit status doesn't confirm that the command used the target
+container's filesystem.
+
+Healthchecks can report incorrect results. Compose services that depend on
+`condition: service_healthy` can remain blocked even when the service they
+need is running.
+
+A container's main process, started by `docker run`, uses the correct
+filesystem. Where your workflow supports it, run setup or readiness checks
+as a container's main command. This avoids the affected exec path for that
+command but doesn't restore exec behavior or ongoing health monitoring.
@@ -18,7 +18,7 @@ sandbox, see [Customize](../customize/).
 - [Models](models.md) selects local models, hosted providers, or custom
  inference endpoints for sandboxed agents.
 - [Environment files](environment-files.md) declare reusable project
-  configuration in `sbxenv.yaml`.
+  configuration in `sbxenv.yaml` for local or cloud sandboxes.
 - [GPU passthrough](gpu-passthrough.md) configures a Linux host and sandbox for
  NVIDIA GPU workloads.
 - [Registry mirror](registry-mirror.md) routes Docker Hub template, kit, and
@@ -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
@@ -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 or cloud 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.
@@ -27,6 +27,10 @@ setup steps.
 > [!NOTE]
 > `sbx env` is experimental. The command interface and file format may change.

+The examples on this page use local sandboxes unless stated otherwise. For
+cloud configuration and lifecycle differences, see
+[Use a cloud environment](#use-a-cloud-environment).
+
 ## Start an environment

 Keep the environment file outside the directories you mount into the sandbox.
@@ -362,6 +366,78 @@ Commands and vault references under `secrets` resolve on the host, so the
 automation runner must provide the referenced tools and authentication. The
 secret values remain outside the environment file.

+### Use a cloud environment
+
+Use `sbx --cloud env` to manage a cloud sandbox from an environment file. For
+account and CLI requirements, see [Cloud sandboxes](../cloud/_index.md).
+
+Save this as `cloud.sbxenv.yaml`:
+
+```yaml
+schemaVersion: "1"
+name: cloud-project
+agent: shell
+
+env:
+  PROJECT_NAME: example
+
+sandboxOptions:
+  cpus: 2
+  memory: 4g
+```
+
+Review the plan, create the sandbox without attaching, and run a command:
+
+```console
+$ sbx --cloud env plan ./cloud.sbxenv.yaml
+$ sbx --cloud env run --detached ./cloud.sbxenv.yaml
+$ sbx --cloud env exec ./cloud.sbxenv.yaml -- printenv PROJECT_NAME
+```
+
+Cloud environments support agents and kits, environment variables, CPU and
+memory limits, credentials for supported providers, and host lifecycle commands.
+Resource limits must match a [cloud size](../cloud/usage.md#choose-resources-and-platform).
+Lifecycle commands still run on your machine with your privileges.
+
+Remove `workspace`, `additionalWorkspaces`, clone options, `ports`, `registries`,
+and MCP server definitions from a local file before using it in cloud mode.
+Cloud environments also reject local sandbox options such as GPU, USB,
+display, shared skills, templates, and governance profiles. These checks run
+before host commands or provisioning. Transfer project files with
+[`sbx --cloud cp`](../cloud/usage.md#transfer-files) or clone a repository inside
+the sandbox.
+
+The plan shows inherited cloud credentials. Sandbox-scoped credentials override
+account defaults, and credentials declared in `secrets` override both. Declare
+literal values or use [`snapshot: true`](#secrets) to resolve a host command or
+vault reference once. Dynamic secret sources and custom credential providers
+aren't supported. Credential bindings require cloud support for kit credentials
+and explicit approval of the kit's injection domains.
+
+Changes to secrets and bindings require recreating the sandbox. Updated `env`
+values apply to subsequent sessions. Rejoining a running agent keeps that
+process's environment.
+
+Use the same machine, Docker identity, cloud endpoint, and ordered file paths
+for later commands. `sbx login` keeps environment state associated with your
+Docker identity. With `DOCKER_ACCESS_TOKEN`, changing the token starts a separate
+state scope.
+
+Remove the environment when you're finished:
+
+```console
+$ sbx --cloud env rm ./cloud.sbxenv.yaml
+```
+
+Removal deletes the sandbox and only the secrets provisioned by this
+environment. Inherited secrets remain. Global bindings remain unless you pass
+`--prune-bindings`. For unattended runs, use `--auto-approve` with `create` or
+`run`, and `--force` with `rm`.
+
+If creation is interrupted, retry the same command and unchanged declaration
+within 23 hours. Unresolved requests prevent removal. Follow the recovery
+message and retain its journal until the original requests are resolved.
+
 ## Review an environment plan

 `sbx env create`, `sbx env run`, and `sbx env rm` show the changes an
@@ -626,6 +702,7 @@ the environment is created.
 | `value`    | string  | None    | Literal secret value                                                         |
 | `ref`      | string  | None    | Vault URI, such as `op://Vault/Item/field`                                    |
 | `command`  | string  | None    | Host shell command whose standard output becomes the secret                   |
+| `snapshot` | boolean | `false` | Resolve `ref` or `command` once on the host and store the result as a literal |
 | `refresh`  | string  | None    | Resolution policy for `ref` or `command`, such as `on-demand` or `55m`        |
 | `backend`  | string  | Automatic | Resolver for `ref`: `sdk` or `cli`                                          |
 | `noVerify` | boolean | `false` | Skip verifying that a `ref` or `command` resolves during provisioning          |
@@ -643,6 +720,21 @@ secrets:
    command: gh auth token
 ```

+For a cloud environment, set `snapshot: true` on a `ref` or `command` source:
+
+```yaml
+secrets:
+  github:
+    command: gh auth token
+    snapshot: true
+```
+
+The command runs on the host after plan approval. The resolved value is stored
+as a literal secret and doesn't refresh. Recreate the environment to rotate
+it. Snapshots also work with local environments. A snapshot can't set
+`refresh` or `noVerify`. Cloud snapshots use CLI resolvers for vault references
+and don't support `backend: sdk`.
+
 ### `bindings`

 `bindings` approves credential injection domains for each service. The
@@ -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
@@ -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.
@@ -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
@@ -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 uses a
+[pay-as-you-go subscription](/manuals/agentic-platform/signup.md#billing).
+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.

+Cloud sandboxes use separate network policy configuration.
+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
@@ -134,7 +143,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.
@@ -152,8 +161,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.

@@ -181,8 +190,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
@@ -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
@@ -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. Cloud sandboxes
+use separate network policy configuration. 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
@@ -34,8 +34,8 @@ For domain patterns, wildcards, CIDR ranges, and filesystem path syntax, see
 Outbound TCP traffic passes through a proxy on your host, which enforces access
 rules on every connection. Non-HTTP TCP traffic, including SSH, can be allowed
 with a hostname rule (for example, `sbx policy allow network "myhost:22"`) or an
-address-based rule. UDP and ICMP are blocked at the network layer and can't be
-unblocked with policy rules.
+address-based rule. UDP requires the experimental feature and policy rules
+described in [Allow outbound UDP](#allow-outbound-udp). ICMP is blocked.

 If you haven't chosen a default preset, the CLI prompts you before it runs a
 sandbox. Running `sbx policy reset` clears the preset and prompts you to choose
@@ -57,7 +57,7 @@ Initialize the global network policy for your sandboxes:

 | Preset      | Description                                                                                                                                       |
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Open        | All outbound traffic is allowed. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`.                                 |
+| Open        | All outbound TCP traffic is allowed. 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. |
 | Locked Down | No baseline allow rules. Destinations need an allow rule from you or a kit. |

@@ -242,6 +242,34 @@ rule-level detail including rule IDs. To inspect a single policy or rule in
 full, use `sbx policy inspect`. See
 [Monitoring](../monitor-and-enforce/monitoring.md).

+### Allow outbound UDP
+
+Outbound UDP is experimental and disabled by default. Turn on experimental
+features and UDP egress before adding UDP allow rules:
+
+```console
+$ sbx settings set platform.allowExperimentalFeatures true
+$ sbx settings set feature.udp-egress true
+$ sbx policy allow network --protocol udp api.example.com:443
+```
+
+Local allow rules apply to TCP by default. Use `--protocol udp` for UDP or
+`--protocol tcp,udp` for both. Deny rules apply to both protocols by default.
+Use `--protocol` to restrict a deny rule to one protocol.
+
+UDP follows the same organization and local policy precedence as TCP. It is
+refused when the destination requires an HTTP, SOCKS5, system, or PAC-selected
+proxy, because those proxies can't carry UDP. ICMP remains blocked.
+
+Inspect UDP rules or check a destination:
+
+```console
+$ sbx policy ls --protocol udp
+$ sbx policy check network --protocol udp api.example.com:443
+```
+
+The CLI warns if you save a UDP rule while UDP egress is disabled.
+
 ## Testing policy

 Before running a sandbox, you can check whether the current policy would allow
@@ -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. Cloud sandboxes
+use separate network policy configuration. 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. A local
@@ -26,10 +30,9 @@ policy. See [Precedence](../concepts.md#precedence).

 ## Rule syntax

-Network rules use the action `connect:tcp`. Resources are hostnames, CIDR
-ranges, ports, or hostnames with ports. The governance policy schema also
-accepts `connect:udp`, but Docker Sandboxes always blocks direct external UDP
-and ICMP. `connect:udp` rules have no effect.
+Network rules use `connect:tcp` for TCP and `connect:udp` for UDP. Resources are
+hostnames, CIDR ranges, ports, or hostnames with ports. UDP requires
+[experimental outbound UDP](local.md#allow-outbound-udp). ICMP is blocked.

 Examples:

@@ -9,9 +9,13 @@ aliases:
  - /ai/sandboxes/governance/org/
 ---

+The governance described here applies to local sandboxes. Cloud sandboxes
+use separate network policy configuration. 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
@@ -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
@@ -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. Cloud sandboxes
+use separate network policy configuration. See
+[Cloud network policy](../cloud/network-policy.md) for cloud controls.
+
 ## Resource model

 Docker sandbox governance is built around two resource types: **policies** and
@@ -77,10 +81,10 @@ plus every team-scoped policy for a team they belong to. See

 ### Network rules

-Network rules use the action `connect:tcp`. Resources are hostnames, CIDR
-ranges, or ports. The governance policy schema also accepts `connect:udp`, but
-Docker Sandboxes always blocks direct external UDP and ICMP. `connect:udp`
-rules have no effect.
+Network rules use `connect:tcp` for TCP and `connect:udp` for UDP. Resources are
+hostnames, CIDR ranges, or ports. UDP requires
+[experimental outbound UDP](access-controls/local.md#allow-outbound-udp).
+ICMP is blocked.

 **Hostname patterns**

@@ -50,6 +50,10 @@ $ sbx policy inspect Balanced
 Use `--source` to filter by origin (`local`, `org`, or `kit`) and `--decision`
 to filter by outcome (`allow` or `deny`).

+Use `--protocol tcp` or `--protocol udp` to filter network rules. The
+`--created-via` filter selects how a rule was created: `default`, `added`,
+`provisioned`, or `approval`.
+
 A `STATUS` column also appears when you pass `--include-inactive`; see
 [Showing inactive rules](#showing-inactive-rules).

@@ -190,7 +194,7 @@ The `PROXY` column shows how the request left the sandbox:
 | `forward`        | Routed through the forward proxy. Supports [credential injection](../../configuration/credentials.md).              |
 | `forward-bypass` | Routed through the forward proxy without credential injection.                                                 |
 | `transparent`    | Intercepted by the transparent proxy. Policy is enforced but credential injection is not available.            |
-| `network`        | Non-HTTP traffic (raw TCP, UDP, ICMP). TCP can be allowed with a policy rule. UDP and ICMP are always blocked. |
+| `network`        | Non-HTTP traffic. TCP and experimental UDP egress follow network policy. ICMP is blocked. |
 | `browser-open`   | A sandbox process requested opening a URL in the host browser. Policy is enforced before opening the URL.      |

 The `RULE` column identifies the policy rule that matched the request. The
@@ -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.45.0 or later for the workflows in these guides.

 ## 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).
@@ -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
@@ -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.

@@ -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.
@@ -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.
@@ -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
@@ -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.
@@ -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
@@ -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.
@@ -49,8 +51,9 @@ What crosses the boundary back to the host:
 Outside the workspace and shared skills store, the agent cannot access your
 host filesystem. It also cannot access your host Docker daemon, your host
 network directly, or any destination not allowed by network policy. Sandboxes
-cannot communicate directly over the network. Direct external UDP and ICMP are
-blocked at the network layer.
+cannot communicate directly over the network. Outbound UDP is blocked unless
+you turn on the [experimental UDP feature](../governance/access-controls/local.md#allow-outbound-udp)
+and allow it through network policy. ICMP is blocked.

 MCP servers are an explicit integration point. Remote MCP servers run outside
 Docker Sandboxes, and local stdio MCP servers run on the host, not inside the
@@ -76,8 +79,8 @@ The sandbox security model has five layers. See
 - **Hypervisor isolation:** separate kernel per sandbox. No shared memory or
  processes with the host.
 - **Network isolation:** outbound TCP traffic is proxied through the host and
-  governed by a [deny-by-default policy](defaults/). Direct external UDP and
-  ICMP are blocked.
+  governed by a [deny-by-default policy](defaults/). Experimental UDP egress
+  also follows network policy. ICMP is blocked.
 - **Docker Engine isolation:** each sandbox has its own Docker Engine with no
  path to the host daemon.
 - **Workspace isolation:** a mountless sandbox has no host workspace mount.
@@ -6,15 +6,18 @@ 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.

 ## Network defaults

 All outbound TCP traffic, including HTTP, HTTPS, and SSH, is blocked unless an
-explicit rule allows the destination. Direct external UDP and ICMP traffic is
-blocked at the network layer. DNS queries use the sandbox's internal resolver,
-which enforces network policy.
+explicit rule allows the destination. Outbound UDP is disabled by default. To
+use it, turn on the [experimental UDP feature](../governance/access-controls/local.md#allow-outbound-udp)
+and add UDP allow rules. ICMP is blocked. DNS queries use the sandbox's internal
+resolver, which enforces network policy.

 Run `sbx policy ls` to see the active network rules for your installation.
 Rules can be customized per machine with the `sbx policy` CLI, or managed
@@ -82,7 +85,7 @@ policy configuration:
  skills store
 - Host Docker daemon
 - Direct network communication between sandboxes
- Direct external UDP and ICMP connections
+- Direct external ICMP connections

 Outbound TCP to destinations not in the allow list is also blocked by default,
 but you can add allow rules with `sbx policy allow`.
@@ -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,
@@ -51,8 +53,10 @@ 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](../configuration/credentials.md) for AI services.

-Direct external UDP and ICMP are blocked at the network layer. DNS queries use
-the sandbox's internal resolver, which enforces network policy. TCP connections
+Outbound UDP is disabled by default. When you turn on
+[experimental UDP egress](../governance/access-controls/local.md#allow-outbound-udp),
+network policy controls its destinations. ICMP is blocked. DNS queries use the
+sandbox's internal resolver, which enforces network policy. TCP connections
 are allowed only when a policy rule matches the destination.

 For the default set of allowed domains, see
@@ -5,6 +5,12 @@ description: Resolve common issues when using Docker Sandboxes.
 keywords: docker sandboxes, sbx, troubleshooting, diagnostics, reset, network policy, git, ssh
 ---

+The following diagnostics and recovery steps apply to local sandboxes. Use
+[`sbx --cloud diagnose`](cloud/usage.md#diagnose-cloud-access) to check cloud
+connectivity and account access. For cloud 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
@@ -156,8 +162,8 @@ can't be recovered. Use an address-based rule in that case:
 $ sbx policy allow network "10.1.2.3:22"
 ```

-UDP and ICMP traffic is blocked at the network layer and can't be unblocked
-with policy rules.
+UDP requires [experimental UDP egress](governance/access-controls/local.md#allow-outbound-udp)
+and UDP allow rules. ICMP is blocked and can't be unblocked with policy rules.

 For Git operations over SSH, you can either add an allow rule for the Git
 server's hostname or IP address, or use HTTPS URLs instead:
@@ -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, templates, save, load
 ---

+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/).

@@ -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
@@ -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.
@@ -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
@@ -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):

@@ -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.

@@ -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:
@@ -32,6 +32,7 @@ see_also:
    - sbx logout - Stop running local sandboxes and sign out of Docker
    - sbx ls - List sandboxes
    - sbx mcp - Manage MCP servers
+    - sbx move - Move a sandbox between local and cloud
    - sbx policy - Manage sandbox policies
    - sbx ports - Manage sandbox port publishing
    - sbx prune - Remove all stopped sandboxes
@@ -84,7 +84,7 @@ options:
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
    - name: on-timeout
      usage: |
-        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
+        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
    - name: publish
      shorthand: p
      default_value: '[]'
@@ -99,7 +99,11 @@ options:
      usage: Suppress verbose output
    - name: skills
      usage: |
-        Shared skills store mode: off, readonly, or readwrite (mounted at the agent's skills directory, e.g. ~/.claude/skills). Default: readonly, or the configured skills.defaultMode setting.
+        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
+    - name: static-mcp
+      default_value: '[]'
+      usage: |
+        MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway.
    - name: template
      shorthand: t
      usage: |
@@ -91,7 +91,7 @@ inherited_options:
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
    - name: on-timeout
      usage: |
-        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
+        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
    - name: publish
      shorthand: p
      default_value: '[]'
@@ -106,7 +106,11 @@ inherited_options:
      usage: Suppress verbose output
    - name: skills
      usage: |
-        Shared skills store mode: off, readonly, or readwrite (mounted at the agent's skills directory, e.g. ~/.claude/skills). Default: readonly, or the configured skills.defaultMode setting.
+        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
+    - name: static-mcp
+      default_value: '[]'
+      usage: |
+        MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway.
    - name: template
      shorthand: t
      usage: |
@@ -91,7 +91,7 @@ inherited_options:
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
    - name: on-timeout
      usage: |
-        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
+        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
    - name: publish
      shorthand: p
      default_value: '[]'
@@ -106,7 +106,11 @@ inherited_options:
      usage: Suppress verbose output
    - name: skills
      usage: |
-        Shared skills store mode: off, readonly, or readwrite (mounted at the agent's skills directory, e.g. ~/.claude/skills). Default: readonly, or the configured skills.defaultMode setting.
+        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
+    - name: static-mcp
+      default_value: '[]'
+      usage: |
+        MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway.
    - name: template
      shorthand: t
      usage: |
@@ -1,125 +0,0 @@
-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 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; a read-only argument may name a single file, which holds
-    that one path out of reach inside a workspace the sandbox can otherwise write.
-
-    Omit the path to create a sandbox without a workspace bind mount: the agent
-    then works in the container's own filesystem instead of on your files.
-
-    Use "sbx run --name SANDBOX" to attach to the agent after creation.
-
-    Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB.
-usage: sbx create copilot [PATH...] [flags]
-options:
-    - name: help
-      shorthand: h
-      default_value: "false"
-      usage: help for copilot
-inherited_options:
-    - name: allow-network
-      default_value: '[]'
-      usage: |
-        Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times)
-    - name: clone
-      default_value: "false"
-      usage: |
-        Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host
-    - name: cloud
-      default_value: "false"
-      usage: |
-        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
-    - name: cloud-api-url
-      default_value: https://api.sandboxes-cloud.docker.com
-      usage: |
-        Cloud Sandboxes API base URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com). Set DOCKER_CLOUD_API_URL or pass this flag to override; a legacy value ending in /v1 is accepted.
-    - name: cpus
-      default_value: "0"
-      usage: |
-        Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs)
-    - name: debug
-      shorthand: D
-      default_value: "false"
-      usage: Enable debug logging
-    - name: deny-network
-      default_value: '[]'
-      usage: |
-        Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
-    - name: env
-      shorthand: e
-      default_value: '[]'
-      usage: |
-        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
-    - name: env-file
-      default_value: '[]'
-      usage: |
-        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
-    - name: image-ref
-      usage: |
-        OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory)
-    - name: kit
-      default_value: '[]'
-      experimental: true
-      usage: |
-        Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times
-    - name: kit-arg
-      default_value: '[]'
-      experimental: true
-      usage: |
-        Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated)
-    - name: kit-args-file
-      default_value: '[]'
-      experimental: true
-      usage: |
-        File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides
-    - 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 (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
-    - name: on-timeout
-      usage: |
-        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
-    - name: publish
-      shorthand: p
-      default_value: '[]'
-      usage: |
-        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
-    - 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)
-    - name: ttl
-      default_value: 0s
-      usage: |
-        Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side)
-    - name: volume
-      shorthand: v
-      default_value: '[]'
-      experimental: true
-      usage: |
-        Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable)
-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
-
-      # Create without a workspace bind mount
-      sbx create copilot
-see_also:
-    - sbx create - Create a sandbox for an agent
@@ -91,7 +91,7 @@ inherited_options:
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
    - name: on-timeout
      usage: |
-        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
+        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
    - name: publish
      shorthand: p
      default_value: '[]'
@@ -106,7 +106,11 @@ inherited_options:
      usage: Suppress verbose output
    - name: skills
      usage: |
-        Shared skills store mode: off, readonly, or readwrite (mounted at the agent's skills directory, e.g. ~/.claude/skills). Default: readonly, or the configured skills.defaultMode setting.
+        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
+    - name: static-mcp
+      default_value: '[]'
+      usage: |
+        MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway.
    - name: template
      shorthand: t
      usage: |
@@ -91,7 +91,7 @@ inherited_options:
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
    - name: on-timeout
      usage: |
-        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
+        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
    - name: publish
      shorthand: p
      default_value: '[]'
@@ -106,7 +106,11 @@ inherited_options:
      usage: Suppress verbose output
    - name: skills
      usage: |
-        Shared skills store mode: off, readonly, or readwrite (mounted at the agent's skills directory, e.g. ~/.claude/skills). Default: readonly, or the configured skills.defaultMode setting.
+        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
+    - name: static-mcp
+      default_value: '[]'
+      usage: |
+        MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway.
    - name: template
      shorthand: t
      usage: |
@@ -91,7 +91,7 @@ inherited_options:
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
    - name: on-timeout
      usage: |
-        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
+        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
    - name: publish
      shorthand: p
      default_value: '[]'
@@ -106,7 +106,11 @@ inherited_options:
      usage: Suppress verbose output
    - name: skills
      usage: |
-        Shared skills store mode: off, readonly, or readwrite (mounted at the agent's skills directory, e.g. ~/.claude/skills). Default: readonly, or the configured skills.defaultMode setting.
+        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
+    - name: static-mcp
+      default_value: '[]'
+      usage: |
+        MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway.
    - name: template
      shorthand: t
      usage: |
@@ -1,125 +0,0 @@
-name: sbx create droid
-synopsis: Create a sandbox for droid
-description: |-
-    Create a sandbox with access to a host workspace for droid.
-
-    The workspace path is 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; a read-only argument may name a single file, which holds
-    that one path out of reach inside a workspace the sandbox can otherwise write.
-
-    Omit the path to create a sandbox without a workspace bind mount: the agent
-    then works in the container's own filesystem instead of on your files.
-
-    Use "sbx run --name SANDBOX" to attach to the agent after creation.
-
-    Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB.
-usage: sbx create droid [PATH...] [flags]
-options:
-    - name: help
-      shorthand: h
-      default_value: "false"
-      usage: help for droid
-inherited_options:
-    - name: allow-network
-      default_value: '[]'
-      usage: |
-        Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times)
-    - name: clone
-      default_value: "false"
-      usage: |
-        Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host
-    - name: cloud
-      default_value: "false"
-      usage: |
-        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
-    - name: cloud-api-url
-      default_value: https://api.sandboxes-cloud.docker.com
-      usage: |
-        Cloud Sandboxes API base URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com). Set DOCKER_CLOUD_API_URL or pass this flag to override; a legacy value ending in /v1 is accepted.
-    - name: cpus
-      default_value: "0"
-      usage: |
-        Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs)
-    - name: debug
-      shorthand: D
-      default_value: "false"
-      usage: Enable debug logging
-    - name: deny-network
-      default_value: '[]'
-      usage: |
-        Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
-    - name: env
-      shorthand: e
-      default_value: '[]'
-      usage: |
-        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
-    - name: env-file
-      default_value: '[]'
-      usage: |
-        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
-    - name: image-ref
-      usage: |
-        OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory)
-    - name: kit
-      default_value: '[]'
-      experimental: true
-      usage: |
-        Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times
-    - name: kit-arg
-      default_value: '[]'
-      experimental: true
-      usage: |
-        Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated)
-    - name: kit-args-file
-      default_value: '[]'
-      experimental: true
-      usage: |
-        File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides
-    - 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 (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
-    - name: on-timeout
-      usage: |
-        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
-    - name: publish
-      shorthand: p
-      default_value: '[]'
-      usage: |
-        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
-    - 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)
-    - name: ttl
-      default_value: 0s
-      usage: |
-        Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side)
-    - name: volume
-      shorthand: v
-      default_value: '[]'
-      experimental: true
-      usage: |
-        Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable)
-example: |4-
-      # Create in the current directory
-      sbx create droid .
-
-      # Create with a specific path
-      sbx create droid /path/to/project
-
-      # Create with additional read-only workspaces
-      sbx create droid . /path/to/docs:ro
-
-      # Create without a workspace bind mount
-      sbx create droid
-see_also:
-    - sbx create - Create a sandbox for an agent
@@ -91,7 +91,7 @@ inherited_options:
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
    - name: on-timeout
      usage: |
-        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
+        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
    - name: publish
      shorthand: p
      default_value: '[]'
@@ -106,7 +106,11 @@ inherited_options:
      usage: Suppress verbose output
    - name: skills
      usage: |
-        Shared skills store mode: off, readonly, or readwrite (mounted at the agent's skills directory, e.g. ~/.claude/skills). Default: readonly, or the configured skills.defaultMode setting.
+        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
+    - name: static-mcp
+      default_value: '[]'
+      usage: |
+        MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway.
    - name: template
      shorthand: t
      usage: |
@@ -1,125 +0,0 @@
-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 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; a read-only argument may name a single file, which holds
-    that one path out of reach inside a workspace the sandbox can otherwise write.
-
-    Omit the path to create a sandbox without a workspace bind mount: the agent
-    then works in the container's own filesystem instead of on your files.
-
-    Use "sbx run --name SANDBOX" to attach to the agent after creation.
-
-    Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB.
-usage: sbx create kiro [PATH...] [flags]
-options:
-    - name: help
-      shorthand: h
-      default_value: "false"
-      usage: help for kiro
-inherited_options:
-    - name: allow-network
-      default_value: '[]'
-      usage: |
-        Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times)
-    - name: clone
-      default_value: "false"
-      usage: |
-        Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host
-    - name: cloud
-      default_value: "false"
-      usage: |
-        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
-    - name: cloud-api-url
-      default_value: https://api.sandboxes-cloud.docker.com
-      usage: |
-        Cloud Sandboxes API base URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com). Set DOCKER_CLOUD_API_URL or pass this flag to override; a legacy value ending in /v1 is accepted.
-    - name: cpus
-      default_value: "0"
-      usage: |
-        Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs)
-    - name: debug
-      shorthand: D
-      default_value: "false"
-      usage: Enable debug logging
-    - name: deny-network
-      default_value: '[]'
-      usage: |
-        Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
-    - name: env
-      shorthand: e
-      default_value: '[]'
-      usage: |
-        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
-    - name: env-file
-      default_value: '[]'
-      usage: |
-        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
-    - name: image-ref
-      usage: |
-        OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory)
-    - name: kit
-      default_value: '[]'
-      experimental: true
-      usage: |
-        Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times
-    - name: kit-arg
-      default_value: '[]'
-      experimental: true
-      usage: |
-        Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated)
-    - name: kit-args-file
-      default_value: '[]'
-      experimental: true
-      usage: |
-        File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides
-    - 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 (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
-    - name: on-timeout
-      usage: |
-        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
-    - name: publish
-      shorthand: p
-      default_value: '[]'
-      usage: |
-        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
-    - 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)
-    - name: ttl
-      default_value: 0s
-      usage: |
-        Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side)
-    - name: volume
-      shorthand: v
-      default_value: '[]'
-      experimental: true
-      usage: |
-        Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable)
-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
-
-      # Create without a workspace bind mount
-      sbx create kiro
-see_also:
-    - sbx create - Create a sandbox for an agent
@@ -91,7 +91,7 @@ inherited_options:
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
    - name: on-timeout
      usage: |
-        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
+        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
    - name: publish
      shorthand: p
      default_value: '[]'
@@ -106,7 +106,11 @@ inherited_options:
      usage: Suppress verbose output
    - name: skills
      usage: |
-        Shared skills store mode: off, readonly, or readwrite (mounted at the agent's skills directory, e.g. ~/.claude/skills). Default: readonly, or the configured skills.defaultMode setting.
+        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
+    - name: static-mcp
+      default_value: '[]'
+      usage: |
+        MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway.
    - name: template
      shorthand: t
      usage: |
@@ -91,7 +91,7 @@ inherited_options:
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
    - name: on-timeout
      usage: |
-        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
+        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
    - name: publish
      shorthand: p
      default_value: '[]'
@@ -106,7 +106,11 @@ inherited_options:
      usage: Suppress verbose output
    - name: skills
      usage: |
-        Shared skills store mode: off, readonly, or readwrite (mounted at the agent's skills directory, e.g. ~/.claude/skills). Default: readonly, or the configured skills.defaultMode setting.
+        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
+    - name: static-mcp
+      default_value: '[]'
+      usage: |
+        MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway.
    - name: template
      shorthand: t
      usage: |
@@ -15,6 +15,16 @@ description: |
    and with --cloud. Snapshots do not refresh; recreate the environment to rotate
    them. A snapshot cannot set refresh or noVerify.

+    Command secrets run from a fresh temporary directory on the host during
+    verification and refresh. The host temporary directory must be absolute and must
+    remain outside writable sandbox mounts. Relative references such as ./helper or
+    cat token no longer resolve against the project or daemon working directory. Use an absolute
+    helper path outside shared workspaces. sbx does not copy helpers, inspect their
+    dependencies, or confine their execution. Helpers and any code or configuration
+    they load must remain outside writable sandbox mounts. Explicit paths into shared
+    workspaces and broad mounts exposing host configuration or the host temporary
+    directory remain unsafe, including mounts added later with sbx mount.
+
      secrets:
        github:
          command: gh auth token
@@ -0,0 +1,102 @@
+name: sbx move
+synopsis: Move a sandbox between local and cloud
+description: |-
+    Move a sandbox between the local host and Docker's hosted Sandboxes service.
+
+    Move captures the sandbox's filesystem as a container image and starts a new
+    sandbox from it on the destination. Running processes and in-memory state do
+    not travel. The destination sandbox gets a new ID; name it with --name.
+
+    Neither direction deletes the source. Moving to cloud stops the local
+    sandbox; restart it with 'sbx run --name <name>'. Moving to local asks the
+    cloud source to stop; a refused or unconfirmed stop warns without failing
+    the move, and the stop may still be finishing when the move returns.
+    'sbx --cloud ls' shows it. A cloud sandbox with no agent is left running.
+    A stopped cloud source keeps its ID and state: 'sbx --cloud run <id>'
+    resumes it, 'sbx --cloud rm <id>' deletes it.
+
+    A failed or cancelled move restores what it can. It restarts a local source
+    that was running and removes the transfer templates it created. The restart
+    re-runs the entrypoint; processes you started by hand are not revived. If a
+    cleanup step fails, the output names what is left and the command that
+    recovers it.
+
+    What does not travel:
+      - The workspace bind mount and other host mounts. Files moved to local
+        stay inside the sandbox at the image's working directory; copy them out
+        with 'sbx cp'.
+      - Secrets managed by sbx. The destination picks its own secrets, so
+        you may need to sign in again. Credentials saved in copied files
+        still travel.
+      - Volumes and environment variables attached to a cloud sandbox, when
+        moving to local. A local sandbox's environment is part of its image
+        and travels to the cloud.
+      - Network policies. Moving to cloud uses cloud policies; moving to local
+        starts with the host's default policy. Active local L7 (HTTP) rules
+        prompt before a move to cloud; --force skips the prompt but keeps
+        the warning.
+      - Cloud URLs and host port bindings. Moving to cloud republishes TCP
+        ports under new cloud URLs; a port the cloud refuses is skipped with a
+        warning. Moving to local saves the published TCP ports and binds them
+        on loopback while the sandbox runs. Host ports can change on restart;
+        'sbx ports SANDBOX' shows them. A cloud port published with an
+        explicit host binding stops a move to local.
+
+    Sizing and disk:
+      - Moving to cloud rounds recorded CPU and memory limits up to a cloud
+        shape. Missing limits use cloud defaults with a warning. Limits above
+        the largest shape stop the move before anything is captured. Moving to
+        local uses local defaults.
+      - Moving to local stages downloaded layers in the host's temporary
+        directory. Reusing local layers can take up to 32 GiB in addition to
+        the local runtime's image storage. If reuse fails, the layers are
+        downloaded. If staging runs out of space, the move falls back to the
+        export stream.
+
+    The cloud sandbox a move creates expires. The default is the server's TTL,
+    typically 1h: stopped in place on expiry when the account and sandbox
+    support it, deleted otherwise. Choose with --ttl and --on-timeout.
+    Extend later with 'sbx --cloud ttl'.
+usage: sbx move SANDBOX [flags]
+options:
+    - name: force
+      shorthand: f
+      default_value: "false"
+      usage: Skip the move confirmation prompt
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for move
+    - name: name
+      usage: |
+        Name for the destination sandbox (default: 'moved-' + the source name; a cloud destination always adds a short unique suffix, a local one only when that name is already taken)
+    - name: on-timeout
+      usage: |
+        What happens to the destination cloud sandbox when its TTL lapses: 'stop' stops it in place so it can be started again later, or 'delete' removes it. Not every sandbox supports 'stop', and an explicit request the server refuses fails the move. Default: stop when the sandbox supports it, else the server default (delete). Only with --to cloud
+    - name: to
+      usage: |
+        Destination of the move: 'local' (cloud to local) or 'cloud' (local to cloud)
+    - name: ttl
+      default_value: 0s
+      usage: |
+        Time-to-live for the destination cloud sandbox (15s to 24h, e.g. 30m, 2h; only with --to cloud; default: server-side)
+inherited_options:
+    - name: cloud
+      default_value: "false"
+      usage: |
+        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+example: |4-
+      # Move a cloud sandbox down to the local host
+      sbx move sbx_abc123 --to local
+
+      # Move a local sandbox up to the cloud
+      sbx move my-sandbox --to cloud
+
+      # Give the destination sandbox a custom name
+      sbx move sbx_abc123 --to local --name big-refactor
+see_also:
+    - sbx - Manage AI coding agent sandboxes.
@@ -115,7 +115,7 @@ options:
        Always create a new cloud sandbox instead of prompting to reuse an existing one (cloud only)
    - name: on-timeout
      usage: |
-        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
+        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
    - name: publish
      shorthand: p
      default_value: '[]'
@@ -126,7 +126,11 @@ options:
      usage: Image pull policy (always|missing|never)
    - name: skills
      usage: |
-        Shared skills store mode: off, readonly, or readwrite (mounted at the agent's skills directory, e.g. ~/.claude/skills). Default: readonly, or the configured skills.defaultMode setting. Can only be used when creating a new sandbox.
+        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting. Can only be used when creating a new sandbox.
+    - name: static-mcp
+      default_value: '[]'
+      usage: |
+        MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time and cannot be changed when re-attaching to an existing sandbox. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway.
    - name: template
      shorthand: t
      usage: |
@@ -17,6 +17,16 @@ description: |-
    Custom secrets apply globally by default. Use --sandbox to scope one to a
    specific sandbox.

+    Command secrets run from a fresh temporary directory on the host during
+    verification and refresh. The host temporary directory must be absolute and must
+    remain outside writable sandbox mounts. Relative references such as ./helper or
+    cat token no longer resolve against the project or daemon working directory. Use an absolute
+    helper path outside shared workspaces. sbx does not copy helpers, inspect their
+    dependencies, or confine their execution. Helpers and any code or configuration
+    they load must remain outside writable sandbox mounts. Explicit paths into shared
+    workspaces and broad mounts exposing host configuration or the host temporary
+    directory remain unsafe, including mounts added later with sbx mount.
+
    With --cloud, --host takes exact DNS names only (no IP addresses or wildcards)
    and the proxy sets --header on requests to those hosts instead of substituting
    the placeholder.
@@ -20,6 +20,16 @@ description: |-
    corresponding op or aws CLI must be installed and authenticated. --command
    runs a shell command and uses its standard output as the secret value.

+    Command secrets run from a fresh temporary directory on the host during
+    verification and refresh. The host temporary directory must be absolute and must
+    remain outside writable sandbox mounts. Relative references such as ./helper or
+    cat token no longer resolve against the project or daemon working directory. Use an absolute
+    helper path outside shared workspaces. sbx does not copy helpers, inspect their
+    dependencies, or confine their execution. Helpers and any code or configuration
+    they load must remain outside writable sandbox mounts. Explicit paths into shared
+    workspaces and broad mounts exposing host configuration or the host temporary
+    directory remain unsafe, including mounts added later with sbx mount.
+
    ### Registry credentials

    Use --registry to store pull credentials for a container registry. Unlike
@@ -4,9 +4,15 @@ experimental: true
 description: |-
    Manage skills available to agents in Docker Sandboxes.

-    Skills are shared across sandboxes by default, mounted read-only. Use
-    --skills=off when creating a sandbox to opt out, or --skills=readwrite to
-    mount the store read-write.
+    Skills are shared across sandboxes by default: the store's entries are linked
+    into the agent's skills directory read-only, which stays writable so kits can
+    install skills beside them. Linking happens at container start, so editing an
+    existing skill is live through the link, while adding a store entry reaches a
+    running sandbox only on its next start. Removing one takes effect immediately:
+    the link in a running sandbox stops resolving at once, and the next start is
+    what clears the stale link away. Use --skills=off when creating a sandbox to
+    opt out, or --skills=readwrite to mount the store over that directory so the
+    sandbox's own writes are shared.
 usage: sbx skills COMMAND
 options:
    - name: help