Sandbox

@vitehub/sandbox gives Vite and Nitro apps one way to define isolated work, call it from your server code, and run it through Cloudflare or Vercel.

Use Sandbox when the code should not run inside the request handler that received the user request. The application keeps a small, typed call site. The provider handles the isolated runtime.

import { readRequestPayload, runSandbox } from '@vitehub/sandbox'

export default defineEventHandler(async (event) => {
  const payload = await readRequestPayload(event, { notes: '' })
  const result = await runSandbox('release-notes', payload)

  if (result.isErr()) {
    throw createError({ statusCode: 500, statusMessage: result.error.message })
  }

  return { result: result.value }
})

import { defineSandbox } from '@vitehub/sandbox'

export default defineSandbox(async (payload: { notes?: string } = {}) => {
  const items = (payload.notes || '')
    .split('\n')
    .map(note => note.replace(/^[-*]\s*/, '').trim())
    .filter(Boolean)

  return {
    summary: items[0] || '',
    items,
  }
})

{
  "result": {
    "summary": "Added weekly digest",
    "items": [
      "Added weekly digest",
      "Tightened signup copy"
    ]
  }
}

What Sandbox solves

Inline request code is the simplest option until the work needs isolation, provider-managed runtime resources, or a stable execution boundary.

Sandbox moves that work behind a named definition:

One portable flow

The same shape works across providers:

1. Register the Vite plugin or Nitro module.
2. Choose cloudflare or vercel in sandbox.provider.
3. Define a named sandbox with defineSandbox().
4. Call it from server code with runSandbox(name, payload).
5. Check result.isOk() or result.isErr().

Discovery model

Nitro discovers sandbox definitions from server/sandboxes/**.

The sandbox name comes from the path under server/sandboxes, without the file extension. server/sandboxes/release-notes.ts becomes release-notes.

Supported providers

Start here

Start with Quickstart for the smallest complete setup. Use the primitive comparison when you are deciding between Sandbox, Queue, inline request code, and other ViteHub primitives.

Next steps