openai/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

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

// 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

// 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)

// 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).

// 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

// 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

// 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