Understanding Sandboxes

Vercel Sandboxes provide on-demand, isolated compute environments for running untrusted code, testing applications, executing AI-generated scripts, and more. Sandboxes are persistent by default: when a sandbox stops, the SDK automatically snapshots its filesystem, and the sandbox configuration is preserved across sessions, so both are restored the next time you resume.

A sandbox is an isolated Linux environment that you create programmatically with the SDK or CLI. Think of it as a secure virtual machine that:

• Boots from a Vercel Managed Image, a custom VCR image, or a saved snapshot
• Uses Ubuntu, Arch Linux, or any other Linux distribution you need
• Has network access for installing packages and making API calls
• Automatically stops after a configurable timeout
• Provides full root access to install any package or binary

Each sandbox includes configurable isolation:

• Filesystem access: A dedicated private filesystem. With persistence enabled (the default), the filesystem is automatically snapshotted on stop and restored when the sandbox resumes. The sandbox configuration is preserved across sessions and reapplied on resume.
• Process isolation: Kernel-level isolation ensures code cannot see or access processes in other sandboxes.
• Network isolation: Each sandbox has its own network namespace with controlled outbound access.

Unlike Docker containers, each sandbox runs in its own Firecracker microVM with a dedicated kernel. This provides stronger isolation than container-based solutions, which makes sandboxes ideal for running untrusted code.

If you already use Docker images to define your environment, store the image in Vercel Container Registry (VCR) and create the sandbox with a custom image. See Images. You can also install packages with your system's package manager, or take a snapshot after setup when a Docker image is not needed.

When you call Sandbox.create(), Vercel provisions a Firecracker microVM on its infrastructure. This microVM boots an Ubuntu 26.04 image, a custom image from VCR, or a saved snapshot.

The sandbox runs on Vercel's infrastructure, so you don't need to manage servers, scale capacity, or worry about availability. Sandboxes provision in the iad1 region by default. You can choose a different region per sandbox or set a project default. See Regions.

Here's what happens during the lifecycle:

1. Provisioning: Vercel allocates compute resources and boots the microVM. Resuming from a snapshot is even faster than starting a fresh sandbox.
2. Running: Your code executes inside a session. A session is a single running VM instance inside a sandbox. You can run commands, install packages, start servers, and interact with the filesystem.
3. Stopping: When the timeout expires or you call stop(), the session shuts down. For persistent sandboxes (the default), the SDK automatically snapshots the filesystem so the next session resumes from the same state. For non-persistent sandboxes, the filesystem is discarded.
4. Resuming: The next SDK call (such as runCommand or writeFiles) on a stopped persistent sandbox starts a new session from the most recent snapshot. You don't need to resume manually.

For long-term storage of data that doesn't belong in the filesystem, write it to external services like databases or object storage.

When you're ready to use a sandbox, you can either create a new one from scratch or use a saved snapshot of a sandbox you created previously. Using a snapshot is much faster than creating from scratch because it avoids reinstalling dependencies and repeating setup steps.

Think of it like the difference between booting a fresh OS install versus resuming from a saved state. A new sandbox gives you a clean slate; a snapshot gives you a pre-configured environment ready to go.

Sandboxes are identified by a name that is unique within your project. If you don't provide one, the SDK generates a name for you. Use the same name later with Sandbox.get() or Sandbox.getOrCreate() to resume the sandbox.

To create a sandbox, you can use the CLI, the JS SDK, or the Python SDK:

# Create a sandbox with a random name
sandbox create
 
# Create with an explicit name
sandbox create --name my-sandbox

Once created, you can run commands inside the sandbox. Commands can run in blocking mode (wait for completion) or detached mode (return immediately).

# Run a command in an existing sandbox (by name)
sandbox exec my-sandbox -- npm install
 
# Run interactively
sandbox exec --interactive --tty my-sandbox -- bash
 
# Run with environment variables
sandbox exec --env DEBUG=true my-sandbox -- npm test

Sandboxes automatically stop after a timeout. The default timeout is 5 minutes, and the maximum applies to each session, not to the sandbox itself. A sandbox spans as many sessions as you resume it for: an agent workspace resumed once a day for a week is one sandbox and seven sessions.

Alternatively, you can stop them manually. stop() resolves once the VM is fully stopped, and returns the final session state. For persistent sandboxes, the resolved value also includes metadata for the snapshot captured during shutdown.

sandbox stop my-sandbox

You can also stop sandboxes from the Vercel Dashboard by navigating to Observability > Sandboxes and clicking Stop Sandbox.

Snapshots save the current state of a sandbox, including all installed packages and files. Use snapshots to skip setup time on subsequent runs, checkpoint long-running tasks, or share environments with teammates.

See Snapshots for complete documentation on creating, retrieving, and managing snapshots.

Vercel Sandboxes are ideal for features that require secure, on-demand code execution:

Sandboxes are not designed to run continuously. They are not suitable for:

• Permanent hosting: If you need a server that stays up 24/7, use a traditional VM or Vercel Functions.
• Long-term storage of large datasets: The filesystem persists between sessions of a persistent sandbox, but it isn't a substitute for a database or object store. Push large or shared data to external services.

Vercel Sandboxes are designed for running untrusted code safely.

Each sandbox runs in its own Firecracker microVM with a dedicated kernel, so you can run processes that require system-level privileges without affecting other sandboxes or the host. These workloads run with sudo and are isolated to your sandbox by the microVM boundary.

Supported workloads include:

• Container runtimes: Run Docker and other container engines inside the sandbox to build images or run containerized workloads.
• VPN clients: Connect to a VPN provider to reach private networks during a session.
• FUSE filesystems: Mount Filesystem in Userspace (FUSE) drivers to attach object storage, network filesystems, or other custom mounts.

These processes require elevated privileges, so run them with sudo. For example, to run a command with elevated privileges through the CLI:

sandbox exec --sudo <name> -- <command>

Outbound network access from these workloads still follows the sandbox firewall network policy. Restrict reachable destinations with a network policy when you run untrusted code.

If you run containers inside the sandbox, the proxy CA certificate is not available inside the container by default. Install it in the container's trust store so HTTPS traffic that the firewall terminates passes TLS verification. See Proxy CA certificates.

Every sandbox comes with:

• A dedicated private filesystem
• Network namespace isolation
• Kernel-level process isolation
• Strict CPU, memory, and disk limits
• Automatic timeouts to prevent runaway processes

These limits prevent resource exhaustion and ensure fair usage across all sandboxes.

Sandboxes can make outbound HTTP requests by default, so you can install packages from public registries like npm or PyPI. Exposed ports are accessible via a public URL, so be mindful of what services you run.

Internet access from the sandbox can be restricted through network policies defined by the users, as part of the sandbox firewall.

To send a sandbox's public-internet traffic through a Secure Compute network's static IPs, and to reach your own AWS VPC over VPC peering, see Using Secure Compute with Sandbox.

Vercel Sandbox mounts a unique, per-sandbox certificate authority (CA) certificate for the sandbox proxy in these locations:

• /etc/pki/ca-trust/source/anchors/vercel-proxy-ca.pem
• /usr/local/share/ca-certificates/vercel-proxy-ca.pem

Vercel Sandbox adds the proxy CA certificate to the system trust bundle automatically. Applications that use the system trust store do not need extra configuration.

The following environment variables are also set so common tools and runtimes use the system CA bundle at /etc/ssl/certs/ca-certificates.crt:

AWS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
CARGO_HTTP_CAINFO=/etc/ssl/certs/ca-certificates.crt
CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
GIT_SSL_CAINFO=/etc/ssl/certs/ca-certificates.crt
GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/certs/ca-certificates.crt
NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
NODE_USE_SYSTEM_CA=1
NPM_CONFIG_CAFILE=/etc/ssl/certs/ca-certificates.crt
PIP_CERT=/etc/ssl/certs/ca-certificates.crt
REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

If your application does not use the system trust store and these environment variables, configure it to trust one of the mounted vercel-proxy-ca.pem files. This is required for HTTPS traffic that the sandbox firewall terminates for transformation rules.

Containers do not inherit the proxy CA. The proxy CA certificate and the CA environment variables are installed on the sandbox host. A container that you run inside the sandbox has its own isolated filesystem and trust store, so it does not inherit either of them. Without the certificate, HTTPS requests from inside the container fail TLS verification when the sandbox firewall terminates them for transformation rules.

To make a container trust the proxy, mount the certificate into the container and add it to the container's own trust store. For example, with Docker:

# Mount the host certificate into the container and trust it at build or run time.
docker run --rm \
  -v /etc/pki/ca-trust/source/anchors/vercel-proxy-ca.pem:/usr/local/share/ca-certificates/vercel-proxy-ca.crt:ro \
  my-image \
  sh -c "update-ca-certificates && my-command"

The exact path and command depend on the container's base image. Place the certificate where that image's trust store expects it, then run the image's trust-update command (for example, update-ca-certificates on Debian or Ubuntu, or update-ca-trust on Amazon Linux, Fedora, or RHEL). For applications that read a CA bundle from an environment variable instead of the system trust store, set the relevant variable (such as NODE_EXTRA_CA_CERTS) to the mounted certificate path inside the container.

Sandboxes run on Vercel's secure infrastructure, which maintains SOC 2 Type II certification. Since sandboxes are ephemeral, they do not persist data long-term. For specific data residency requirements, consult your plan details or compliance team.

• Persistent sandboxes: Sandboxes that auto-save state and resume where you left off.
• Tags: Categorize sandboxes by environment, team, or any other criteria using key-value tags.
• Drives: Attach persistent filesystem storage to sandboxes and reuse data across sandbox runs.
• Regions: Choose where your sandboxes run and configure failover regions.
• Secure Compute: Send a sandbox's public-internet traffic through a network's static IPs, and reach your own VPC over VPC peering.
• Quickstart: Run your first sandbox.
• Working with Sandbox: Task-oriented guides for common operations.
• Authentication: Configure SDK authentication.
• Snapshots: Save and restore sandbox state.
• JS SDK Reference: Full API documentation for JavaScript and TypeScript.
• Python SDK Reference: Full API documentation for Python.
• CLI Reference: Manage sandboxes from the terminal.
• Examples: Real-world use cases and code samples.