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
   uv init
   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

   uv add vercel 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

   import asyncio
    
   from dotenv import load_dotenv
   from vercel import sandbox
    
   load_dotenv('.env.local')
    
    
   async def main() -> None:
       async with sandbox.create_sandbox(persistent=False) as box:
           result = await box.run_process(
               'echo',
               ['Hello from Vercel Sandbox!'],
               capture_output=True,
               check=True,
           )
           print(result.stdout)
    
    
   asyncio.run(main())

4. Run it

   TypeScriptPython
   Terminal

   pnpm tsx index.ts

   Terminal

   uv run python main.py

   You should see: Hello from Vercel Sandbox!

   Sandboxes automatically stop after 5 minutes by default. They are also persistent by default: the filesystem is snapshotted on stop and restored the next time you resume the sandbox by name. To adjust the timeout, opt out of persistence, or manage running sandboxes, see Working with Sandbox.

   Automatic snapshots count toward Snapshot Storage. For one-off workloads, pass persistent: false (or --non-persistent in the CLI) to opt out. See Persistent Sandboxes for details.

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.

• 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.
• Snapshots: Save sandbox state to skip setup on future runs.
• Examples: See real-world use cases.