FAQ

Answers to common questions about Sandbox SDK. Pricing, providers, keys, browsers, edge runtimes, Docker, failures, and how it compares to calling a provider directly.

Is Sandbox SDK a hosted service?

No. It is an npm package that runs in your server. It calls each provider’s API or SDK with your credentials, and nothing runs between you and the provider. There is no account to create with us.

What does it cost?

The SDK is free and MIT licensed. You pay each provider for the sandboxes you run on it, at their prices. Local and Memory cost nothing beyond your own machine.

Why not call the provider’s API or SDK directly?

You can, and box.native gives you the provider’s API, or its own SDK object, whenever you need it. The SDK adds what most apps end up writing themselves: one API across providers, get-or-create by key, background processes that survive a restart, readiness checks, file editing and diffs, git with hidden tokens, secret redaction, output caps, ready-made agent tools, and errors with codes you can branch on.

Can I switch providers later?

Yes. Change the import and the factory. Options a new provider can’t enforce fail at createSandbox with unsupported, so you find the differences right away. Existing sandboxes don’t move between providers.

Can I use it in the browser?

No. Provider keys would be exposed. Call it from a server, a server action, a route handler, or a worker, and send results to the browser.

Does it run on edge runtimes?

No. It needs Node 22+ or Bun 1.3+, so use a Node route or function instead of Next.js middleware or another edge runtime.

Do I need Docker?

Only for the Local provider. Memory needs nothing, and the cloud providers run machines for you.

Why didn’t my command throw?

A command that exits non-zero, times out, or is aborted is a normal result with ok: false. Check result.ok or result.exitCode. The SDK throws SandboxError only when the sandbox, the provider, or the request fails. See Running commands.

Why did `cd` in one command not apply to the next?

Each run is a fresh shell, so state doesn’t carry over by design. Pass cwd and env on each call, or chain commands with && in one call.

Why does `createSandbox` throw `unsupported`?

You asked for something the provider can’t enforce, such as a network allow list on Local or a size on E2B. The SDK refuses rather than ignore the option. The error message says what the provider allows, and the capability matrix lists every limit.

Why did my sandbox survive the end of the block?

It has a key. With a key, await using calls close(), which leaves the sandbox running for the next request. Without a key, it calls destroy(). Call box.destroy() yourself to delete a keyed sandbox, and set up cleanup.

Two requests created two sandboxes for the same key. Why?

Best-effort providers, such as E2B and Daytona, find sandboxes by searching, so simultaneous requests can both miss. Within one process the SDK prevents this. Across servers, pass a locator with withLock. See One sandbox per user.

My dev server is running but the preview doesn’t load.

Check three things. The server must listen on 0.0.0.0, not localhost. On providers that route only declared ports, the port must be in ports at creation. On providers with private previews, requests need the header from preview.headers, so a plain iframe won’t work. The ports and Preview URL rows of the capability matrix say which providers need each, and Dev servers and previews shows the fix.

FAQ