The sbx move command transfers a filesystem snapshot between a local sandbox
and a cloud sandbox. Use it to continue working in the other environment
from a snapshot of your files. Running processes and memory don't transfer.
Transfer behavior
A move performs the following operations:
- Captures the source sandbox filesystem as a template image
- Transfers the image across the local and cloud boundary
- Creates a destination sandbox from the image
The destination gets a different sandbox ID. The source isn't deleted, and changes made to either sandbox after the move aren't synchronized. Verify the destination before removing the source.
Files and credentials
ImportantManaged 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
Before you move
Check platform compatibility
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.
Choose a destination name
Use --name to set the exact destination name in either direction.
The name must be available at the destination.
If the name is already taken, the command reports an error before confirmation,
source capture, or transfer. Local names are compared case-insensitively. Cloud
names must be available within the source agent's namespace.
Confirm or cancel the move
Review the CLI warnings before confirming a move. Use --force to skip
confirmation prompts. This skips the prompts without changing what transfers.
If you decline a move confirmation, the move is canceled and the command returns
a nonzero exit status. In a shell command chain using &&, commands after
sbx move won't run when you decline.
Move from local to cloud
Move a local sandbox to the cloud:
$ sbx move local-project --to cloud
The move command spans both backends, so don't add the global --cloud flag.
Without --name, the cloud destination gets an automatically generated name
with a short unique suffix. Use --name to set the exact destination name:
$ sbx move local-project --to cloud --name cloud-project
Workspace files
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. Using --force doesn't include those files.
Network rules and ports
The destination uses cloud network policy and the network rules of the
sandbox's kit, or of its built-in agent, as sbx --cloud create does. Network
rules you added locally 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.
Credentials and resources
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. 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:
$ 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.
To restart the destination automatically when it expires, use restart:
$ sbx move local-project --to cloud --ttl 4h --on-timeout restart
The restart action stops and immediately starts the destination. If you
specify --ttl, it must be at least one hour.
These flags apply only to moves to the cloud. After the move, inspect or extend
the expiration with sbx --cloud ttl.
Source sandbox state
A local-to-cloud move stops the local source while capturing its filesystem. The source isn't deleted. Remove it separately after verifying the cloud destination.
Move from cloud to local
Move a cloud sandbox to the local runtime by ID or name:
$ sbx move cloud-project --to local --name local-copy
This direction requires a machine that meets the local sandbox requirements because the command imports the snapshot and creates a local sandbox. Layer reuse during download can require up to 32 GiB of temporary host disk space in addition to the local runtime's image storage.
Network rules and ports
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 port ls local-copy to see the bindings.
Files and resources
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.
Source sandbox state
After creating the local destination, the move attempts to stop the cloud
source. This is a best-effort operation: the source can remain running if it
can't be stopped, and the move can return before the stop finishes. Check
sbx --cloud ls for its state. A cloud source with no agent is left running.
The source remains available until you remove it with sbx --cloud rm.
Verify the result
List both backends after the move:
$ 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.