Vercel Sandbox
Vercel Sandbox fits Vercel-hosted apps that want isolated execution without adding a second platform. ViteHub keeps the public sandbox API stable and forwards runtime settings to Vercel where they matter.
Before you start
Install the Vercel SDK alongside @vitehub/sandbox.
pnpm add https://pkg.pr.new/vite-hub/vitehub/@vitehub/sandbox@main @vercel/sandbox
Set Vercel sandbox credentials in the runtime environment when the provider cannot inherit them automatically.
VERCEL_TOKEN=your-token
VERCEL_TEAM_ID=your-team-id
VERCEL_PROJECT_ID=your-project-id
ViteHub reads these values from process.env. Nuxt, Nitro, Vite, or your process manager must load .env before startup.
Configure Vercel
export default defineNuxtConfig({
modules: ['@vitehub/sandbox/nuxt'],
sandbox: {
runtime: 'node22',
},
})
On Vercel hosting, ViteHub uses the Vercel sandbox provider automatically. Set app-wide defaults in top-level sandbox config. Override them per sandbox only when one sandbox needs different runtime limits.
Define a sandbox
Sandbox definitions accept only portable options (timeout, env, runtime). Set Vercel-specific options such as cpu, ports, source, and networkPolicy in the top-level sandbox config.
import { defineSandbox } from '@vitehub/sandbox'
export default defineSandbox(async (payload?: { notes?: string }) => {
return { notes: payload?.notes || '' }
}, {
timeout: 60_000,
})
What changes on Vercel
| Concern | Behavior |
|---|---|
| Runtime defaults | Configure app-wide defaults such as runtime, timeout, cpu, and ports in top-level sandbox config. |
| Provider options | Set cpu, ports, source, and networkPolicy in the top-level sandbox config, not in defineSandbox(). |
| Credentials | ViteHub reads token, teamId, and projectId from config or VERCEL_TOKEN, VERCEL_TEAM_ID, and VERCEL_PROJECT_ID. |
| Execution model | ViteHub resolves the named sandbox and asks Vercel to run it inside Vercel's sandbox runtime. |
sandbox.provider = 'vercel' in config and use NITRO_SANDBOX_TOKEN, NITRO_SANDBOX_TEAM_ID, NITRO_SANDBOX_PROJECT_ID, NUXT_SANDBOX_TOKEN, NUXT_SANDBOX_TEAM_ID, or NUXT_SANDBOX_PROJECT_ID when you need runtime-specific credentials.runSandbox() stays the same.