ViteHub

Docker Sandbox

Configure Docker Sandbox and run isolated sandboxes locally.

Docker Sandbox fits local development and self-hosted Node setups. Docker gives you a predictable local sandbox runtime before you move the same sandbox API to a hosted provider.

Before you start

Install @vitehub/sandbox and make sure Docker Desktop or Docker Engine is available on the machine that runs Nitro.

Terminal
pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/sandbox@main

Configure Docker

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@vitehub/sandbox/nuxt'],
  sandbox: {
    provider: 'docker',
    workspace: process.cwd(),
    template: 'node:22-bookworm',
  },
})

Set workspace to the project root that Docker should mount. Change template only when your sandbox needs a different base image.

Define a sandbox

Sandbox definitions accept only portable options (timeout, env, runtime). Set Docker-specific options such as template, pullTemplate, and readinessTimeout in the top-level sandbox config.

server/sandboxes/release-notes.ts
import { defineSandbox } from '@vitehub/sandbox'

export default defineSandbox(async (payload?: { notes?: string }) => {
  return { notes: payload?.notes || '' }
}, {
  timeout: 30_000,
})

What changes on Docker

ConcernBehavior
Image templateUse template and pullTemplate to control the container image ViteHub should use.
Workspace accessDocker mounts your configured workspace so the sandbox can read project files locally.
Runtime scopeDocker is local-first. It supports execution and file operations, but not public URL publishing.
Choose Docker when you want the fastest way to iterate on sandbox code locally before you commit to a hosted provider.

Deno

Configure Deno Sandbox and run isolated sandboxes on Deno Deploy.

Local

Run sandboxes locally with OS-level isolation using platform primitives.