Cloudflare Sandbox
Use Cloudflare Sandbox when isolated runs should stay close to the rest of a Cloudflare-based stack. ViteHub handles the Durable Object integration and keeps the Cloudflare-specific settings in the top-level sandbox config.
If you want the Worker Loader-based runtime instead, use Cloudflare Dynamic Workers. That provider stays explicit and does not share the Durable Object runtime path.
Before you start
Install the Cloudflare SDK alongside @vitehub/sandbox.
pnpm add https://pkg.pr.new/vite-hub/vitehub/@vitehub/sandbox@main @cloudflare/sandbox
You also need a Cloudflare deployment so ViteHub can provision the sandbox runtime.
Configure Cloudflare
export default defineNuxtConfig({
modules: ['@vitehub/sandbox/nuxt'],
})
On Cloudflare hosting, ViteHub uses the Durable Object sandbox provider automatically. Set binding only when you need to override the default Durable Object binding name.
Cloudflare-specific options
Set Cloudflare-specific options such as sandboxId, keepAlive, sleepAfter, and normalizeId in the top-level sandbox config. These are provider settings, not definition options.
export default defineNuxtConfig({
modules: ['@vitehub/sandbox/nuxt'],
sandbox: {
sandboxId: 'release-notes',
keepAlive: true,
sleepAfter: '10m',
},
})
Define a sandbox
Sandbox definitions accept only portable options (timeout, env, runtime).
import { defineSandbox } from '@vitehub/sandbox'
export default defineSandbox(async (payload?: { notes?: string }) => {
return { notes: payload?.notes || '' }
}, {
timeout: 30_000,
})
What changes on Cloudflare
| Concern | Behavior |
|---|---|
| Sandbox identity | Use sandboxId when repeated calls should reuse the same Cloudflare sandbox identity. |
| Binding resolution | ViteHub resolves the Durable Object binding from sandbox.binding or falls back to the default Cloudflare binding. |
| Provider options | Use keepAlive, sleepAfter, and normalizeId in the top-level sandbox config. |
sandboxId undefined when every execution should stay ephemeral.