Sandboxes

A sandbox is a private Linux machine with Node, pnpm and git, ready in seconds. Put files in, run commands, start a server and get a preview link. Each one is kept apart from your app and from every other sandbox, so it's a safe place for generated or untrusted code.

Good for: builds and tests, dev servers with live preview, running code an AI wrote. Billed: by size, only while running.

Add the Sandboxes service to an app once, then start as many sandboxes as you need (up to 50 per app).

SizesCopy Anchor Link

Asleep costs nothingCopy Anchor Link

A sandbox falls asleep after 15 minutes without use (you can choose 1 minute to 24 hours), and you stop paying. Its files are kept: everything in /workspace, installed packages included, is saved when it falls asleep or stops and is back when it wakes, so you pick up where you left off with nothing to reinstall. Up to 2 GB is kept; set keep_dependencies: false to save less and reinstall instead. Turn it off with keep_files: false for a fresh machine every time.

Set it up once. Give it a setup_command (or "Run when it starts" in the dashboard), like pnpm install. It runs before anything else, and only again if its saved files are gone. For tools installed outside /workspace, like apt-get install -y ffmpeg, set setup_runs: "every_start".

Previews are private. A preview link from the dashboard, the API or the sandbox_preview_url tool works for an hour; open it, or share it, and that browser gets in. Without the link, the preview says it's private. Set public_preview: true for a preview anyone with the address can open. Platforms that show previews in their own pages can limit who frames them, renew access without reloading and add their own script: see Previews inside your own pages.

Need a browser? Start it with image: "browser" (or "With a browser" in the dashboard) for Chromium and everything Playwright needs, for screenshots, visual checks and browser tests. It costs the same. Your own images aren't supported yet.

Watching a long command? The dashboard terminal shows output as it comes, and the API sends it as it happens with stream: true (execStream() in the SDK).

Use oneCopy Anchor Link

const app = ocp.app(appId)
const sandbox = await app.sandboxes.create({ size: 'standard-1', label: 'Preview build' })
const box = app.sandbox(sandbox.id)

await box.writeFiles({ 'package.json': pkg, 'src/index.ts': code })
const { exit_code, stdout } = await box.exec('pnpm install && pnpm test')

await box.startProcess('dev', 'pnpm dev --host 0.0.0.0 --port 5173')
const url = await box.previewUrl(5173) // share this

• exec runs a command and waits (up to 10 minutes). A string runs in a shell; an array runs without one.
• startProcess runs something that keeps going, like a dev server. Check on it with process(name), stop it with stopProcess(name).
• Change files while a server runs: tools with hot reload pick the changes up.

Agents do the same with the create_sandbox, sandbox_write_files, sandbox_exec and sandbox_start_process tools. In the dashboard, the Sandboxes panel has a terminal to try commands.

Stop or deleteCopy Anchor Link

Stop a sandbox when you're done to stop paying straight away (Stop in the dashboard, stop(), or the stop_sandbox tool). Start it again with Start, start() or start_sandbox: it comes back with its files (unless it doesn't keep them). Delete it to remove it from the list.