Sandbox
Use Sandbox to run server-side handlers in an isolated runtime when the job needs filesystem, process, or network isolation without introducing a queue or durable workflow.
Define sandboxes in server/sandboxes/** with defineSandbox(handler, options?), then execute them with runSandbox().
Getting started
Install the package
Install @vitehub/sandbox and the SDK for the provider you plan to use.
pnpm add https://pkg.pr.new/vite-hub/vitehub/@vitehub/sandbox@main @cloudflare/sandbox
Configure a provider
export default defineNuxtConfig({
modules: ['@vitehub/sandbox/nuxt'],
sandbox: {
provider: 'cloudflare',
},
})
Define a sandbox
Add a sandbox module under server/sandboxes/. ViteHub derives the sandbox name from the path inside that directory. For example, server/sandboxes/release-notes.ts registers release-notes.
type ReleaseNotesPayload = {
notes?: unknown
}
export default defineSandbox(async (input?: ReleaseNotesPayload) => {
const { notes } = await readValidatedPayload(input, value => ({
notes: typeof value?.notes === 'string' ? value.notes.trim() : '',
}))
const items = notes
.split(/\n+/)
.map(line => line.replace(/^[-*]\s*/, '').trim())
.filter(Boolean)
return {
summary: items[0] || 'No notes provided.',
items: items.slice(0, 3),
}
}, {
timeout: 30_000,
})
Run the sandbox
Call the named sandbox from any server-side code. runSandbox() returns a result object, so check for errors before you return the value.
import { createError, readBody } from 'h3'
import { runSandbox } from '@vitehub/sandbox'
export default defineEventHandler(async (event) => {
const body = await readBody<{ notes?: unknown }>(event)
const result = await runSandbox('release-notes', body)
if (result.isErr()) {
throw createError({
statusCode: 500,
statusMessage: result.error.message,
data: {
code: result.error.code,
provider: result.error.provider,
},
})
}
return result.value
})
Public API
| Function | Use it for |
|---|---|
defineSandbox(handler, options?) | Register one sandbox by exporting it from the sandboxes directory. |
runSandbox(name, payload, { context? }) | Execute that sandbox from a route, task, or webhook. |
Type reference
Handler signature
The handler receives an optional payload and an optional context object, and returns the result directly.
type SandboxHandler<TPayload, TResult> = (
payload?: TPayload,
context?: Record<string, unknown>,
) => TResult | Promise<TResult>
SandboxDefinitionOptions
The options object passed to defineSandbox() accepts portable options that work across all providers:
| Option | Type | Description |
|---|---|---|
timeout | number | Maximum execution time in milliseconds. |
env | Record<string, string> | Environment variables passed to the sandbox. |
runtime | { command, args? } | Custom runtime command for the sandbox process. |
cpu, ports, or sandboxId belong in the top-level sandbox config in nitro.config.ts, not in the definition.Result<T>
runSandbox() returns a Result<T> instead of throwing. Check the result before accessing the value.
| Method / Field | Type | Description |
|---|---|---|
isOk() | boolean | true when execution succeeded. |
isErr() | boolean | true when execution failed. |
value | T | The handler return value. Only safe after isOk(). |
error | SandboxError | Error details with message, code, provider, and details. |
Configure provider and sandbox options
Sandbox has two configuration layers:
- Top-level
sandboxconfig selects the provider and sets app-wide defaults. defineSandbox(handler, options?)andcreateSandbox(options?)(handler)both configure one sandbox file with portable options such astimeoutandenv. ::
defineSandbox(handler, options?)configures one sandbox file with portable options such astimeoutandenv.
runSandbox() is not configuration. It is the execution call, so that is where you pass the payload and optional per-request context.
export default defineNuxtConfig({
sandbox: {
provider: 'vercel',
},
})
export default defineSandbox(async (payload) => {
return { ok: true }
}, {
timeout: 30_000,
})