vercel-sandbox

# Vercel Sandbox > **CRITICAL — Your training data is outdated for this library.** Vercel Sandbox APIs are new (GA January 2026) and likely not in your training data. Before writing sandbox code, **fetch the docs** at https://vercel.com/docs/vercel-sandbox and the SDK reference at https://vercel.com/docs/vercel-sandbox/sdk-reference to find the correct `Sandbox.create()` options, `runCommand()` signatures, file I/O methods (`writeFiles`, `readFile`), port exposure, and cleanup patterns. Do not guess — look up the exact API shape. The GitHub repo at https://github.com/vercel/sandbox has working examples for common patterns (code execution, FFmpeg processing, dev server spawning). You are an expert in Vercel Sandbox — ephemeral compute for safely running untrusted code. ## Status & Pricing Vercel Sandbox is **generally available** (January 30, 2026). The CLI and SDK are open-source. Powered by the same Firecracker infrastructure that runs 2M+ Vercel builds per day. | Resource | Hobby (Free) | Pro / Enterprise | |----------|-------------|-----------------| | CPU hours | 5 / month | $0.128 / CPU-hour | | Provisioned memory | 420 GB-hr / month | $0.0106 / GB-hr | | Network bandwidth | 20 GB / month | $0.15 / GB | | Sandbox creations | 5,000 / month | $0.60 / 1M creations | Each sandbox can use up to **8 vCPUs** and **2 GB RAM per vCPU**. Up to **4 ports** can be exposed per sandbox. ## What It Is Vercel Sandbox provides **Firecracker microVMs** with millisecond startup times for running untrusted or user-generated code in complete isolation. Used by AI agents, code generation tools, developer playgrounds, and interactive tutorials. - **Base OS**: Amazon Linux 2023 (with `git`, `tar`, `openssl`, `dnf`) - **Runtimes**: `node24` (default since March 2026), `node22`, `python3.13` - **Working directory**: `/vercel/sandbox` - **User**: `vercel-sandbox` with `sudo` access - **Filesystem**: Ephemeral — artifacts must be exported before sandbox stops - **GitHub**: https://github.com/vercel/sandbox ## Key APIs Package: `@vercel/sandbox` (v1.8.0+) ### Create and Run Commands ```ts import { Sandbox } from '@vercel/sandbox'; // Create a sandbox (env vars available to all commands) const sandbox = await Sandbox.create({ runtime: 'node24', // 'node24' | 'node22' | 'python3.13' env: { // inherited by all runCommand calls NODE_ENV: 'production', API_KEY: process.env.API_KEY!, }, }); // Run a command (separated command + args) const result = await sandbox.runCommand('node', ['-e', 'console.log(42)']); const output = await result.stdout(); // "42\n" // Run with options (per-command env overrides creation-level env) const result2 = await sandbox.runCommand({ cmd: 'npm', args: ['install', 'express'], cwd: '/vercel/sandbox/app', env: { NODE_ENV: 'development' }, // overrides creation-level NODE_ENV sudo: true, }); // Detached execution (long-running processes) const cmd = await sandbox.runCommand({ cmd: 'node', args: ['server.js'], detached: true, }); // Stream logs in real-time for await (const log of cmd.logs()) { console.log(`[${log.stream}] ${log.data}`); } await cmd.wait(); // block until completion ``` ### File Operations ```ts // Write files (takes array of { path, content: Buffer }) await sandbox.writeFiles([ { path: 'app.js', content: Buffer.from('console.log("hello")') }, { path: 'package.json', content: Buffer.from('{"type":"module"}') }, ]); // Read a file (returns Buffer or null) const buf = await sandbox.readFileToBuffer({ path: 'app.js' }); // Read as stream const stream = await sandbox.readFile({ path: 'app.js' }); // Download to local filesystem await sandbox.downloadFile('output.zip', './local-output.zip'); // Create directory await sandbox.mkDir('src/components'); ``` ### Source Initialization ```ts // Clone a git repo const sandbox = await Sandbox.create({ source: { type: 'git', url: 'https://github.com/user/repo', depth: 1 }, }); // Mount a tarball const sandbox = await Sandbox.create({ source: { type: 'tarball', url: 'https://example.com/project.tar.gz' }, }); // Restore from snapshot const sandbox = await Sandbox.create({ source: { type: 'snapshot', snapshotId: 'snap_abc123' }, }); ``` ### Snapshots (Save and Resume VM State) ```ts // Capture full VM state (filesystem + packages) // WARNING: sandbox shuts down after snapshot creation const snapshot = await sandbox.snapshot({ expiration: 86400_000 }); // 24h console.log(snapshot.snapshotId); // List and manage snapshots const { snapshots } = await Snapshot.list(); const snap = await Snapshot.get({ snapshotId: 'snap_abc' }); await snap.delete(); ``` ### Network Policies (SNI Filtering + CIDR) Egress firewall uses **SNI filtering** on TLS client-hello — outbound connections are matched at the handshake and unauthorized destinations are rejected before data transmits. For non-TLS traffic, IP/CIDR rules are also supported. Policies can be updated at runtime without restarting the sandbox process, enabling multi-step workflows (e.g., open access during setup → deny-all before running untrusted code). ```ts // Lock down before running untrusted code await sandbox.updateNetworkPolicy('deny-all'); // Allow specific domains only (SNI filtering) await sandbox.updateNetworkPolicy({ allow: ['api.openai.com', '*.googleapis.com'], }); // Credential brokering (inject API keys so untrusted code never sees them) await sandbox.updateNetworkPolicy({ allow: { 'ai-gateway.vercel.sh': [{ transform: [{ headers: { 'x-api-key': process.env.SECRET_KEY! } }], }], }, }); ``` ### Public URLs and Lifecycle ```ts // Expose a port and get a public URL const sandbox = await Sandbox.create({ ports: [3000] }); const url = sandbox.domain(3000); // public URL // Extend timeout await sandbox.extendTimeout(300_000); // +5 minutes // Clean up await sandbox.stop(); // Check status sandbox.status; // 'pending' | 'running' | 'stopping' | 'stopped' | 'failed' // Resource tracking (after stop) sandbox.activeCpuUsageMs; sandbox.networkUsage; // { ingress, egress } in bytes ``` ### List and Rehydrate ```ts // List existing sandboxes const { sandboxes } = await Sandbox.list({ limit: 10 }); // Reconnect to a running sandbox const sandbox = await Sandbox.get({ sandboxId: 'sbx_abc123' }); ``` ## Timeout Limits | Plan | Max Timeout | |------|------------| | Default | 5 minutes | | Hobby | 45 minutes | | Pro/Enterprise | 5 hours | ## Agent Patterns 1. **Safe AI code execution**: Run AI-generated code without production risk 2. **Snapshot-based fast restart**: Install deps once → snapshot → create from snapshot (skip setup) 3. **Network isolation**: Allow all during setup → `deny-all` before untrusted code 4. **Credential brokering**: Inject API keys via network policy transforms 5. **Live preview**: Expose ports via `sandbox.domain(port)` for generated apps 6. **File I/O workflow**: `writeFiles()` → execute → `readFileToBuffer()` results ## When to Use - AI agents need to execute generated code safely - User-submitted code execution (playgrounds, tutorials) - Code review validation (used by Vercel Agent) - Ephemeral development environments ## When NOT to Use - Production workloads → use Vercel Functions - Long-running services → use a dedicated server - Simple function execution → use Serverless Functions ## References - 📖 docs: https://vercel.com/docs/vercel-sandbox - 📖 SDK reference: https://vercel.com/docs/vercel-sandbox/sdk-reference - 📖 GitHub: https://github.com/vercel/sandbox