Vercel Sandbox allows you to run arbitrary code in isolated Linux microVMs.
Sandboxes are persistent by default: the filesystem is snapshotted when a
session stops and restored when it resumes. View the documentation
here.
A sandbox is an isolated Linux system for your experimentation and use.
Internally, it is a Firecracker MicroVM that is powered by the same
infrastructure that powers 2M+ builds a day at Vercel.
Getting started
To get started using Ubuntu with Node.js 24, create a new project:
mkdir my-sandbox-app && cd my-sandbox-appnpm init -yvercel link
The SDK uses Vercel OIDC tokens to authenticate whenever available. This is the
most straightforward and recommended way to authenticate.
When developing locally, you can download a development token to .env.local
using vercel env pull. After 12 hours the development token expires, meaning
you will have to call vercel env pull again.
In production, Vercel manages token expiration for you.
Access token
If you want to use the SDK from an environment where VERCEL_OIDC_TOKEN is
unavailable, you can also authenticate using an access token:
Go to your team settings, and copy the team ID.
Go to a project's settings, and copy the project ID.
Go to your Vercel account settings and create a token. Make
sure it is scoped to the team ID from the previous step.
Set your team ID, project ID, and token to the environment variables
VERCEL_TEAM_ID, VERCEL_PROJECT_ID, and VERCEL_TOKEN. Then pass these to
the create method:
const sandbox = await Sandbox.create({ teamId: process.env.VERCEL_TEAM_ID!, projectId: process.env.VERCEL_PROJECT_ID!, token: process.env.VERCEL_TOKEN!, source: { url: "https://github.com/vercel/sandbox-example-next.git", type: "git", }, resources: { vcpus: 4 }, // Defaults to 5 minutes. The maximum is 24 hours for Pro/Enterprise, and 45 minutes for Hobby. timeout: ms("5m"), ports: [3000],});
Workflow DevKit integration
Sandbox and CommandFinished support serialization with the
Workflow DevKit. When a sandbox instance
crosses a step boundary the SDK serializes sandbox metadata and routes, then
rehydrates synchronously from that snapshot. Deserialized instances lazily
recreate an API client using OIDC or environment credentials when needed.
Limitations
Max resources: 4 vCPUs on Hobby, 8 vCPUs on Pro, 32 vCPUs on Enterprise. You will get 2048 MB of memory per vCPU.
Sandboxes have a maximum duration of 24 hours for Pro/Enterprise and 45 minutes for Hobby,
with a default of 5 minutes. This can be configured using the timeout option of Sandbox.create().
Default image
Sandboxes use
vercel/sandbox/universal:latest
by default. This Ubuntu-based image includes Node.js 24, Bun, Python 3.14,
coding agents, and common development and debugging utilities. It runs as the
ubuntu user with passwordless sudo.
Vercel Managed Images
Vercel provides several public images optimized to use in Sandbox. The
Dockerfiles for Vercel Managed Images published under vercel/sandbox/* live
in the images/
directory:
The image option accepts a repository in the sandbox's project, with an
optional tag or digest. A bare repository name resolves to the latest tag.
You can also pass a fully-qualified VCR URL:
Writes are delivered in call order. writeStdin resolves once the process has
accepted the data, and fails after 30 seconds if the process isn't reading.
You can also pass a Readable, with or without detached. It's written in
order with backpressure, and stdin closes when it ends:
The stream is never destroyed. If piping fails or the stream errors,
runCommand rejects and kills the command; when detached, the next
cmd.wait() rejects instead. If the command exits first, piping just stops.
Retries never deliver bytes twice. If a write still fails, later writes are
rejected; closeStdin still works.
Write to a command from one place at a time, or bytes can be skipped as
already written.
Each write is one API request against your rate limit, so batch small
writes.
In workflows, use stdin: true (a stream can't cross steps), and await each
write. Ordering only holds within a step.
Multi-user
Sandboxes support creating isolated Linux users with their own home directories,
file permissions, and process ownership. This is useful for multi-agent workflows
where each agent needs its own workspace, or for simulating multi-user
environments.
Note: The sandbox image must have /bin/bash installed. It is the login
shell for created users and is used to wrap commands that run as a user. The
Vercel managed images include it.
Creating users
import { Sandbox } from "@vercel/sandbox";const sandbox = await Sandbox.create();// Creates /home/alice with isolated permissionsconst alice = await sandbox.createUser("alice");alice.username; // "alice"alice.homeDir; // "/home/alice"
createUser sets up:
A Linux user with /bin/bash as the default shell
A home directory at /home/<username> group-owned by the sandbox's default user group with 770 permissions
Running commands as a user
All commands run as the user by default, with the working directory set to their
home:
writeFiles, readFile, readFileToBuffer, and mkDir all resolve relative
paths against the user's home directory. Written files are owned by the user:
const alice = await sandbox.createUser("alice");// Writes to /home/alice/app.js, owned by alice:aliceawait alice.writeFiles([ { path: "app.js", content: Buffer.from('console.log("hi")') },]);// Read it backconst buf = await alice.readFileToBuffer({ path: "app.js" });buf?.toString(); // 'console.log("hi")'// Stream readsconst stream = await alice.readFile({ path: "app.js" });// Create directories owned by the userawait alice.mkDir("projects/my-app"
File isolation
Users cannot access each other's home directories:
const alice = await sandbox.createUser("alice");const bob = await sandbox.createUser("bob");await alice.writeFiles([ { path: "secret.txt", content: Buffer.from("alice only") },]);// Bob cannot read, list, or write to alice's homeconst cat = await bob.runCommand({ cmd: "cat", args: ["/home/alice/secret.txt"],});cat.exitCode; // non-zero — Permission denied
The SDK can read all users' files because home directories are group-owned
by the sandbox's default user group. Both SandboxUser methods and direct
sandbox methods work:
// Via SandboxUser (relative paths resolve to home dir)const buf = await alice.readFileToBuffer({ path: "secret.txt" });buf?.toString(); // "alice only"// Via sandbox directly (absolute path required)const buf2 = await sandbox.readFileToBuffer({ path: "/home/alice/secret.txt" });buf2?.toString(); // "alice only"
Groups and shared directories
Create groups to let users collaborate through a shared directory:
const devs = await sandbox.createGroup("devs");devs.sharedDir; // "/shared/devs"await sandbox.addUserToGroup("alice", "devs");await sandbox.addUserToGroup("bob", "devs");// Alice writes to the shared directoryawait alice.runCommand({ cmd: "bash", args: ["-c", 'echo "spec v2" > /shared/devs/spec.txt'],});// Bob can read it — files inherit group ownership via setgidconst spec = await bob.runCommand({ cmd: "cat", args: [
Shared directories use setgid (2770), so files created inside them
automatically inherit the group. All group members get read/write access.