Sandbox Regions

Sandboxes run in a region that you choose when you create them. Pick the region closest to the data sources your sandboxes talk to, such as databases or object storage, to reduce latency.

分镜故事板 is available in 19 regions:

The default region is iad1.

When you create a sandbox, Vercel resolves the region in this order:

1. The region you pass when creating the sandbox.
2. Your project's default sandbox region, configured in the project settings.
3. iad1 when no region was specified.

Pass the region when you create the sandbox:

sandbox create --name my-sandbox --region sfo1

import { Sandbox } from '@vercel/sandbox';
 
const sandbox = await Sandbox.create({
  name: 'my-sandbox',
  region: 'sfo1',
});
 
console.log(sandbox.region); // "sfo1"

Read the region of an existing sandbox with the sandbox.region accessor in the SDK, or from the REGION column of sandbox list in the CLI.

To change the region for all sandboxes a project creates, without passing region on every call:

1. From the Vercel dashboard, select your project and go to Settings, then Sandboxes.
2. Under Sandbox Regions, select the main region.
3. Select Save.

You can also set the project defaults with Vercel CLI (this is the vercel CLI, not the sandbox CLI):

# Set the default region and failover regions for the project
vercel project update my-project --sandbox-region sfo1 --sandbox-failover-regions cle1,iad1
 
# Clear them
vercel project update my-project --sandbox-region "" --sandbox-failover-regions ""

To view a project's configured sandbox regions, run vercel project inspect my-project and check the Sandbox section.

New sandboxes that don't specify a region use the project default. Existing sandboxes keep the region they were created in.

Failover regions let sandbox creation succeed even when the main region is unavailable. When Vercel can't provision capacity in the main region, it tries the failover regions in the order you list them.

A snapshot doesn't need to be available in a failover region for failover to work. Vercel loads it across regions for you, as described in Regions and snapshots.

Teams on the Hobby plan or a Pro trial can set the main region, but can't configure or use failover regions. Requests that include failover regions fail with a payment_required error. If your team moves to the Hobby plan, Vercel ignores previously configured failover regions when creating sandboxes.

Pass failover regions when creating a sandbox, or set them as a project default in the same Sandbox Regions settings section:

sandbox create --name my-sandbox --region iad1 --failover-regions cle1,sfo1

import { Sandbox } from '@vercel/sandbox';
 
const sandbox = await Sandbox.create({
  name: 'my-sandbox',
  region: 'iad1',
  failoverRegions: ['cle1', 'sfo1'],
});

Failover regions must not include the sandbox's main region. Failover regions are also not supported for sandboxes that mount drives.

To change the failover regions of an existing sandbox, pass failoverRegions to sandbox.update() in the SDK (use [] to remove them) or run sandbox config failover-regions <name> <region,...|none> in the CLI.

A snapshot is stored in the region of the sandbox it was created from. You can only create or resume a sandbox from a snapshot in a region where that snapshot is available. Creating a sandbox from a snapshot in another region fails with a snapshot_region_mismatch error.

This applies to persistent sandboxes too: a persistent sandbox resumes from its latest snapshot, so that snapshot must be available in the sandbox's region.

The same rule applies to forks. A fork runs in the source sandbox's region unless you pass region. If the source has a snapshot, that snapshot must be available in the target region.

Snapshots can't be moved between regions. To run an environment in another region, create a new sandbox in that region, run your setup again, and snapshot it there.

Read the regions where a snapshot is available with the snapshot.regions accessor in the SDK, or from the REGIONS column of sandbox snapshots list in the CLI.

A drive is stored in a single region. Choose the region when you create the drive, with the --region option in the CLI or the region parameter in Drive.getOrCreate(). Drives are created in iad1 when you don't specify a region:

sandbox drives get-or-create workspace-cache --region sfo1

import { Drive } from '@vercel/sandbox';
 
const drive = await Drive.getOrCreate({
  name: 'workspace-cache',
  region: 'sfo1',
});
 
console.log(drive.region); // "sfo1"

A drive's region can't change after creation, and drives can't be moved between regions. Requesting an existing drive with a different region fails with a conflict error.

A sandbox that mounts a drive must run in the same region as the drive; otherwise creation fails with a drive_region_mismatch error.

The project default region is not applied to sandboxes that mount drives. Pass region explicitly to match the drive's region when it's not iad1.

Failover regions are not supported for sandboxes that mount drives, because a drive is only available in its own region. Configuring both fails with a bad_request error.

Read the region of an existing drive with the drive.region accessor in the SDK, or from the REGION column of sandbox drives list in the CLI.

Active CPU, Provisioned Memory, Sandbox Data Transfer, and Drive rates vary by region. See Regional pricing for the rates in each region. Sandbox Creations and Snapshot Storage are billed at the same rate in all regions where Sandbox is available.

• Snapshots: Save and restore sandbox state.
• Drives (Beta): Attach persistent storage to sandboxes.
• Pricing and Quotas: Snapshot storage rates and sandbox quotas.
• JS SDK Reference: The region and failoverRegions parameters.
• CLI Reference: The --region and --failover-regions options.