Local Sandbox
Local Sandbox runs sandbox code directly on your machine using Node.js filesystem operations and OS-level process isolation. Local requires no cloud accounts, containers, or external SDKs.
Before you start
Install @vitehub/sandbox. The local provider has no additional dependencies.
pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/sandbox@main
Configure Local
export default defineNuxtConfig({
modules: ['@vitehub/sandbox/nuxt'],
sandbox: {
provider: 'local',
},
})
provider field entirely in development.Define a sandbox
import { defineSandbox } from '@vitehub/sandbox'
export default defineSandbox(async (payload?: { notes?: string }) => {
return { notes: payload?.notes || '' }
})
How isolation works
The local provider wraps every exec() call with OS-level sandboxing when available. File operations use plain Node.js fs against an isolated temporary directory.
Platform detection
ViteHub selects the strongest isolation available on the current platform:
| Platform | Method | What it does |
|---|---|---|
| macOS | sandbox-exec (seatbelt) | Allows reads everywhere, restricts writes to the sandbox temp directory and /tmp. |
| Linux | bwrap (bubblewrap) | Bind-mounts system paths as read-only, gives the sandbox write access only to its temp directory. Uses PID namespace isolation. |
| Other | None | Commands run without a wrapper. File isolation still applies through the temp directory. |
Detection runs once when the sandbox is created. The adapter logs which isolation method is active.
Seatbelt profile (macOS)
The generated profile allows all default operations, then denies writes globally and re-allows writes only to the sandbox temp directory and /tmp:
(version 1)
(allow default)
(deny file-write* (subpath "/"))
(allow file-write* (subpath "<tempDir>"))
(allow file-write* (subpath "/tmp"))
(allow file-write* (subpath "/private/tmp"))
(allow file-write* (subpath "/private/var/folders"))
(allow file-write* (subpath "/var/folders"))
(allow file-write* (literal "/dev/null"))
(allow file-write* (literal "/dev/tty"))
(allow process-fork)
(allow process-exec)
Bubblewrap (Linux)
The adapter bind-mounts /usr, /lib, /bin, and /etc as read-only, then gives the sandbox read-write access to its own temp directory. It also enables --unshare-pid, --new-session, and --die-with-parent for process isolation.
What changes on Local
| Concern | Behavior |
|---|---|
| File storage | All sandbox files live in a system temp directory. The directory is removed when stop() is called. |
| Command execution | Commands are wrapped with seatbelt or bubblewrap when available. Falls back to direct execution. |
| Runtime scope | Local is development-first. It supports execution and file operations, but not public URL publishing or long-running processes. |