Skip to main content
You can move a sandbox from the v1 region (us-va-1) to the v2 region (us-phx-1) with the SDK. The migration copies the sandbox filesystem and the template it depends on to the target region, where the sandbox is paused under the same Sandbox ID until you resume it. You can also distribute one of your own templates to the target region on its own, without moving any sandbox. Migration requires novita-sandbox 2.1.3 or later.

Before You Start

Your account needs access to both regions and the migration feature. You also need an API key, the source region name, and the Sandbox ID you want to move.
Create one client for each region. The source region name and the domain of each region are listed in the Regions table. Use the name from that table as the source region. Do not derive it from the domain.
The source client pauses the sandbox. The target client starts the migration, polls the job, and connects to the migrated sandbox. The target region is whichever region the target client points at, so there is no separate target region parameter. The rest of this guide uses these two clients.

Migrate Sandboxes

Once the migration completes, the sandbox is no longer available in the source region. In the target region it is paused, and you need to resume it yourself. If the sandbox was created with auto resume enabled, that setting carries over, and the sandbox resumes on the next request without a manual step.

Migrate a Sandbox

Only a sandbox in the paused state can be migrated. The service copies the files from the source sandbox and the template it was built from to the target region. When migration completes, the sandbox is paused in the target region under the same Sandbox ID. Connect through the target client to resume it. The template’s start command (start_cmd) runs again in the target region and launches a fresh application process. Commands you started by hand, for example with sandbox.commands.run, are not replayed. If the template has no start command, or your application is started some other way, connect to the migrated sandbox and start it yourself.
1

Pause the Source Sandbox

Stop your workload, save the state you need to files, then pause the sandbox. pause returns before the sandbox has finished pausing, so poll getInfo / get_info until the state is paused before you submit the migration. If the sandbox is already paused, skip to the next step.
2

Start the Migration

The template the sandbox depends on is handled as part of the migration, so you do not need to distribute it first. If the target region reports a template name conflict, you can rename the template there by passing an optional template alias (templateAlias in JavaScript, template_alias in Python). This only works for templates you own, not for public templates owned by another account. See Template Alias for the naming rules.
3

Wait for the Job

Migration time: Plan for approximately 5–15 minutes to migrate a single sandbox. Larger snapshots, more layers, or batch migrations may take longer. This estimate is for planning purposes only; actual duration depends on how the job progresses.
While the migration runs, leave the source sandbox alone. That includes SDK commands, file operations, and direct requests to the sandbox URL. Do not use the source sandbox to judge progress.The code below keeps waiting on the same job ID after a timeout, and stops the flow if the job fails or is cancelled. Only continue to the next step when wait returns a result.
A timeout on wait does not cancel the server-side job and does not mean the migration failed. The loop above calls wait again with the same job ID. Do not create a new job. If the job fails or is cancelled, the code raises and the flow ends. Keep the job ID, check the job items with job.get, and check the source sandbox state before you decide what to do next.To check progress at any time:
4

Connect in the Target Region

Only connect once the job is completed, has no failed or cancelled items, and the item for your sandbox is completed. Check this in code before you call connect, then connect with the same Sandbox ID through the target client:
connect resumes the sandbox from its paused state. In the migrated sandbox, commands run as root by default, with /root as the working directory. The example passes user and cwd explicitly to keep the user and working directory the source sandbox used. Pass them on every command and file operation that depends on the original user. Check your files, the application state, and access to external services. If the application is not running, start it with sandbox.commands.run. Send all further requests to the target domain.

Migrate Several Sandboxes

You can submit several sandboxes in one job:

Distribute Templates

Distribution copies the template. It only migrates data that has been persisted to disk; in-memory data is not migrated. After it completes, the template is available in both the source and the target region.

Distribute a Template

You can distribute a template to the target region on its own, without migrating any sandbox. The template becomes available there under the alias you choose, and you can create new sandboxes from it right away. Distribution takes the Template ID, and the template alias is required:
The check above only passes when the job is completed, has no failed or cancelled items, and the template item is completed. Then create a sandbox from the alias:

Distribute Several Templates

You can submit several templates in one job. The batch uses one source region, and the target region comes from the target client’s domain.
Every alias in the batch is checked for conflicts and ownership in the same way as a single alias. See Template Alias.

Template Alias and Public Templates

Choosing an Alias

An alias is the template name you pass when creating a sandbox, such as my-agent-base. To migrate a sandbox you only need its Sandbox ID. The service looks up the template it depends on and decides whether the target name can be reused. You only need a Template ID when you distribute a template on its own.
  • If the name is free, or the existing name can be reused, the migration goes ahead.
  • If the name conflicts, the request is rejected and no job is created. Change the alias and submit again.
A name conflict returns:
You can leave the alias out when migrating a sandbox. The service then uses the source name, or the Template ID if there is no source name. The default name is still checked for conflicts, and the SDK does not generate a new name for you.

Sandboxes Built on Another Account’s Public Template

In regions that support cross-account template migration, the service resolves the template dependency based on who owns the template and whether it is public. The migrated sandbox is still yours, and you connect to it with the target domain and the same Sandbox ID. Migrating a sandbox does not transfer someone else’s template to you, and it does not create an alias for that template under your account. Passing a template alias does not change ownership either. The alias check still runs when the request is accepted, and a conflict returns the error above. A completed migration does not guarantee that the source alias is available in the target region, or that the template stays public. To create new sandboxes from it, use a Template ID or alias you can access in the target region. If the owner makes the template private, you may no longer be able to create sandboxes from it. Access to a public template does not include permission to modify or delete it.

Job Status, Cancellation, and Troubleshooting

Job Status

The job response reports a status per item but not the full internal failure reason. When you contact support, include the job ID, the Sandbox ID or Template ID, the source region, the target domain, the time of the failure, and the error message.

Cancel a Job

A reverting status means the cancellation was accepted and cleanup is still running. Poll with job.get until the job reaches a final state. A job in its last phase may not be cancellable, so go by what the cancel call returns. A cancelled or failed job does not restore the source sandbox automatically. Check the rollback result and the source sandbox state before you reconnect to it or migrate again.

Common Issues

Never include your API key in error logs, support tickets, or code samples.

FAQ

What do I need to do before using a Volume in a migrated sandbox?

The migrated sandbox needs the NFS client dependencies before it can mount a Volume. If nfs-common is not installed, install it inside the sandbox first, then mount the Volume. For a sandbox that uses apt-get, run the following after connecting to the migrated sandbox:
Python
This example requires the user account to have passwordless sudo access.
Last modified on November 18, 2026