Compare local and cloud sandboxes | Docker Docs
Share feedback
Answers are generated based on the documentation.

Compare local and cloud sandboxes

Table of contents

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.

CapabilityLocal sandboxCloud sandbox
ComputeUses resources from the hostUses Docker-managed cloud resources
CPU architectureUses the platform supported by the local runtimeSupports linux/amd64 and linux/arm64, subject to account availability; moves must retain the source platform
WorkspaceMounts host paths or uses a private Git clone backed by the host repositoryHas no access to host paths; transfer files or clone a repository inside the sandbox
HardwareCan use supported host integrations, such as GPU, USB, display, and nested virtualizationHas no access to host hardware
PortsBinds sandbox ports to host addresses and portsExposes a sandbox port through a public HTTPS URL
SecretsReads from the local sbx secret storeReads from the separate sbx --cloud secret store
Network policyUses local and organization policy sources supported by the local runtimeUses separate, network-only account and sandbox policy; local policies aren't copied
MCP serversUses servers registered in the local MCP storeUses servers connected through Docker Agentic Platform
StoragePersists in the local sandbox and its attached host resourcesPersists in the cloud sandbox and optional cloud volumes
LifetimePersists across stops until you remove itExpires according to its time-to-live and timeout action
BillingNo metered sandbox compute chargePay-as-you-go compute

If your workflow runs Docker inside the sandbox, review the Docker exec and healthcheck limitation. 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 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 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 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 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.

StateLocal to cloudCloud to localWhat to do
Network policyLocal rules aren't copied; the CLI warns that cloud policy appliesCloud rules aren't copied; the CLI notice explains that the host's default egress policy appliesConfigure destination rules and verify allowed and blocked connections before continuing work
Managed secretsUses applicable credentials in the cloud secret storeUses applicable credentials in the local secret storeConfigure credentials in the destination store; the CLI warns that secrets aren't copied and you may need to sign in again
Workspace and attached storageHost mounts and clone-mode volumes aren't copied; a workspace triggers a warning and confirmationCloud volumes aren't copied and no host folder is mountedTransfer needed files separately with sbx cp
Published portsTCP ports get cloud URLs; refused ports are skipped with a warningPorts use local loopback bindings; cloud URLs aren't retainedInspect destination ports and update clients
CPU and memoryRounds recorded source limits up to a supported cloud size; missing limits use defaults with a warningUses local defaultsCheck destination resources and workload performance; sbx move has no CPU or memory override flags
CPU architectureCloud access must support the source platformThe local runtime must support the source platformMatch platforms; the CLI checks compatibility before transfer

The managed-secret warning doesn't itself block a move. Configure cloud credentials or local credentials 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 before removing the source.