Quickstart

This guide shows you how to run your first code in a Vercel Sandbox.

• A Vercel account
• Vercel CLI installed (npm i -g vercel)
• Node.js 22+ or Python 3.10+

1. Set up your environment

   Create a new directory and connect it to a Vercel project. This is the recommended way to authenticate because the project handles secure OIDC token authentication for you.

   TypeScriptPython
   Terminal

   mkdir my-sandbox-app && cd my-sandbox-app
   pnpm init
   vercel link

   Terminal

   mkdir my-sandbox-app && cd my-sandbox-app
   vercel link

   When prompted, select Create a new project. The project doesn't need any code deployed. It needs to exist so Vercel can generate authentication tokens for you.

   Once linked, pull your environment variables to get an authentication token:

   Terminal

   vercel env pull

   This creates a .env.local file containing a token that the SDK uses to authenticate your requests. When you deploy to Vercel, token management happens automatically.

2. Install the SDK

   TypeScriptPython
   npmyarnpnpmbun

   Terminal

   npm install @vercel/sandbox dotenv @types/node tsx typescript

   Terminal

   yarn add @vercel/sandbox dotenv @types/node tsx typescript

   Terminal

   pnpm add @vercel/sandbox dotenv @types/node tsx typescript

   Terminal

   bun add @vercel/sandbox dotenv @types/node tsx typescript

   dotenv is used to access environment variables within your application. The tsx package is a TypeScript runner that allows you to run your TypeScript code. The typescript package is the TypeScript compiler. The @types/node package is the TypeScript definitions for the Node.js API.

   Terminal

   pip install vercel-sandbox python-dotenv

3. Write your code

   Create a file that creates a sandbox and runs a command:

   TypeScriptPython
   index.ts

   import { config } from 'dotenv';
   config({ path: '.env.local' });
    
   import { Sandbox } from '@vercel/sandbox';
    
   async function main() {
     const sandbox = await Sandbox.create();
    
     const result = await sandbox.runCommand('echo', ['Hello from Vercel Sandbox!']);
     console.log(await result.stdout());
   }
    
   main().catch(console.error);

   main.py

   from dotenv import load_dotenv
   from vercel.sandbox import Sandbox
    
   load_dotenv('.env.local')
    
   sandbox = Sandbox.create()
    
   result = sandbox.run_command('echo', ['Hello from Vercel Sandbox!'])
   print(result.stdout())

4. Run it

   TypeScriptPython
   Terminal

   pnpm tsx index.ts

   Terminal

   python main.py

   You should see: Hello from Vercel Sandbox!

   Sandboxes automatically stop after 5 minutes. To adjust this or manage running sandboxes, see Working with Sandbox.

1. Set up authentication: Connected to a Vercel project and pulled credentials to enable sandbox creation.
2. Created a sandbox: Spun up an isolated Linux microVM.
3. Ran a command: Executed code inside the secure environment.

• SDK Reference: Full API documentation for TypeScript and Python.
• CLI Reference: Manage sandboxes from the terminal.
• Snapshots: Save sandbox state to skip setup on future runs.
• Examples: See real-world use cases.