Vercel Sandbox

Vercel Sandbox is an ephemeral compute primitive designed to safely run untrusted or user-generated code on Vercel. It supports dynamic, real-time workloads for AI agents, code generation, and developer experimentation.

With Vercel Sandbox, you can:

• Execute untrusted or third-party code: When you need to run code that has not been reviewed, such as AI agent output or user uploads, without exposing your production systems.

• Build dynamic, interactive experiences: If you are creating tools that generate or modify code on the fly, such as AI-powered UI builders or developer sandboxes such as language playgrounds.

• Test backend logic in isolation: Preview how user-submitted or agent-generated code behaves in a self-contained environment with access to logs, file edits, and live previews.

• Run a development server to test your application.

• The Vercel CLI

To create a sandbox, use the @vercel/sandbox SDK and follow these steps:

1. Install @vercel/sandbox

   From your terminal:

   terminal

   mkdir sandbox-test
   cd sandbox-test
   pnpm init
   pnpm add @vercel/sandbox ms
   pnpm add -D @types/ms @types/node

2. Link a project

   From the sandbox-test directory you just created, link a new or existing project:

   terminal

   vercel link

   Then pull the project's environment variables:

   terminal

   vercel env pull

   This pulls a Vercel OIDC token into your .env.local file that the SDK will use to authenticate with.

3. Create the set up file

   In the code below, you set up a sandbox with 4 vCPUs that uses node22 runtime and will do the following:

   • Clone a Github repository of a Next.js application
   • Install the dependencies for the application
   • Run a next dev server and listen to port 3000
   • Open the sandbox URL (sandbox.domain(3000)) in a browser and stream logs to your terminal
   • The sandbox will stop after the timeout of 5 minutes that you set with timeout
   next-dev.ts

   import ms from 'ms';
   import { Sandbox } from '@vercel/sandbox';
   import { setTimeout } from 'timers/promises';
   import { spawn } from 'child_process';
    
   async function main() {
     const sandbox = await Sandbox.create({
       source: {
         url: 'https://github.com/vercel/sandbox-example-next.git',
         type: 'git',
       },
       resources: { vcpus: 4 },
       timeout: ms('5m'), //timeout in milliseconds: ms('5m') = 300000
       ports: [3000],
       runtime: 'node22',
     });
    
     console.log(`Installing dependencies...`);
     const install = await sandbox.runCommand({
       cmd: 'npm',
       args: ['install', '--loglevel', 'info'],
       stderr: process.stderr,
       stdout: process.stdout,
     });
    
     if (install.exitCode != 0) {
       console.log('installing packages failed');
       process.exit(1);
     }
    
     console.log(`Starting the development server...`);
     await sandbox.runCommand({
       cmd: 'npm',
       args: ['run', 'dev'],
       stderr: process.stderr,
       stdout: process.stdout,
       detached: true,
     });
    
     await setTimeout(500);
     spawn('open', [sandbox.domain(3000)]);
   }
    
   main().catch(console.error);

4. Start the sandbox

   Run the following command in your terminal:

   terminal

   node --env-file .env.local --experimental-strip-types ./next-dev.ts

   Once the application opens in your browser, you can view the logs in the terminal as you interact with it.

5. Access the sandbox

   You can connect to the sandbox from any application programmatically by using sandbox.domain(3000) to return the URL of the sandbox. The sandbox will terminate after 5 minutes based on the 300000 ms timeout you set.

   To stop the sandbox before the timeout, you can:

   • Use the SDK stop method
   • From the list of sandboxes in the Observability tab of your project, select the sandbox and click Stop

• Each sandbox can use a maximum of 8 vCPUs with 2 GB of memory allocated per vCPU. Review limitations.
• You can run Node.js or Python runtimes. Review the system specifications.
• Review the available SDK methods.

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.

If you want to use the SDK from an environment where VERCEL_OIDC_TOKEN is unavailable, you can also authenticate using an access token. You will need

• your Vercel team ID
• your Vercel project ID
• a Vercel access token with access to the above team

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 },
  timeout: ms('5m'), //timeout in milliseconds: ms('5m') = 300000
  ports: [3000],
  runtime: 'node22',
});

To view sandboxes that were started per project, inspect the command history and view the sandbox URLs, access the Sandboxes insights page by:

• From the Vercel dashboard, go to the project where you created the sandbox
• Click the Observability tab
• Click Sandboxes on the left side of the Observability page

To track compute usage for your sandboxes across projects, go to the Usage tab of your Vercel dashboard.

Vercel tracks sandbox usage by:

• Active CPU: The amount of CPU time your code consumes, measured in milliseconds. Waiting for I/O (e.g. calling AI models, database queries) does not count towards Active CPU.
• Provisioned memory: The memory size of your sandbox instances (in GB), multiplied by the time they are running (measured in hours).
• Network bandwidth: The incoming and outgoing network traffic in and out of your sandbox for tasks such as installing packages and sandbox usage by external traffic through the sandbox listening port.
• Sandbox creations: The number of times you started a sandbox.

If you exceed the above allotment, you can continue using sandboxes under Pro and Enterprise plans based on the following regional pricing:

At any time, based on your plan, you can run up to a maximum number of sandboxes at the same time. You can upgrade if you're on Hobby. For Pro and Enterprise, this limit will not apply during the Beta period.