onbox - Local sandboxes and microVMs for macOS and Linux.

Run untrusted code, AI agent output, or dev environments in isolated containers on your own machine.

Install

# CLI
npm install -g onbox

# SDK
npm install onbox

CLI

# Create a sandbox and open a shell
onbox create --image node:22 --connect

# One-shot: run a command and clean up
onbox run --image python:3 -- python -c "print('hello')"

# Mount a host directory into the sandbox
onbox create --image node:22 --mount ~/dev/project:/workspace --connect

# Execute commands in a running sandbox
onbox exec sbx_abc123 npm test
onbox exec -w /workspace -e CI=true sbx_abc123 npm run build

# Copy files between host and sandbox
onbox copy ./local-file.txt sbx_abc123:/app/file.txt
onbox copy sbx_abc123:/app/dist/ ./output/

# Pause, resume, stop
onbox pause sbx_abc123
onbox resume sbx_abc123
onbox stop sbx_abc123

# Snapshots: save state and restore later
onbox snapshot sbx_abc123
onbox create --snapshot snap_abc123

# List and manage
onbox list
onbox snapshots list
onbox host status

Full CLI reference: docs/cli.md

SDK

import Onbox from "onbox"

const onbox = await Onbox()

const sandbox = await onbox.create({
	image: "node:22",
	mounts: [{ src: "~/dev/project", dst: "/workspace" }],
	env: { NODE_ENV: "production" },
})

const result = await sandbox.runCommand("npm", ["test"], { cwd: "/workspace" })
console.log(result.exitCode) // 0
console.log(await result.stdout()) // "Tests passed..."

await sandbox.stop()

Full SDK reference: docs/sdk.md

Features

Any Docker image. Use node:22, python:3, ubuntu:24.04, or anything from Docker Hub.

Host mounts. Mount directories from your machine into the sandbox with near-native speed via virtiofs.

Resource limits. Set CPU and memory limits per sandbox.

Snapshots. Capture the full sandbox state (filesystem, installed packages) and restore it later. Skip setup steps by snapshotting after npm install and creating fresh sandboxes from the snapshot.

Pause and resume. Freeze a sandbox and all its processes. Resume later exactly where you left off.

Background processes. Spawn long-running processes (dev servers, watchers) and monitor them. Stream stdout/stderr, wait for completion, or kill them.

Filesystem operations. Read, write, and download files programmatically.

Environment variables. Set env vars at sandbox creation and override them per command. Sandbox-level vars are passed to every command automatically.

Timeouts. Auto-stop sandboxes after a duration. Extend the timeout at runtime if you need more time.

Offline. Everything runs locally. No internet connection required after initial image pull.

Uses Apple's Virtualization framework (vz) on macOS for near-native performance. On Linux, it uses QEMU.

License

MIT