stackbox

The command line for stackbox, the hosted router for sandbox providers. stackbox puts E2B, Modal, Daytona, Blaxel and Cloudflare Containers behind one OpenSandbox-compatible API and one key.

Quickstart

Get an API key from your org's admin, or create one in the console at https://app.box.stacktrace.ai. Then install the client, log in once, and run a command:

pip install stackbox

stackbox auth login

stackbox run --name hello ubuntu:24.04 -- echo hello

stackbox run creates a sandbox, runs the command and streams its output. The first line on stderr gives the sandbox's name, its id and the provider that got it. While the sandbox starts, a live line on the terminal shows each provider that stackbox tries. The sandbox stays running for your next commands:

stackbox exec hello -- echo again

stackbox delete hello

Without --name, the sandbox gets a generated name, such as brave-otter. Add --rm to delete the sandbox after the command.

Commands

A bare verb acts on a sandbox, as in Docker: stackbox run, stackbox list. Anything else has a noun: stackbox image list. Every command takes --json.

SANDBOX is a sandbox's name, its id, or the start of its id when no other sandbox's id starts the same way.

run and create take these options before --:

stackbox run --rm -e GREETING=hi --timeout 1h python:3.13 -- python3 -c 'import os; print(os.environ["GREETING"])'

run and exec exit with the command's exit code. They exit with 125 when stackbox cannot start the sandbox or run the command, as docker run does. Costs are estimates from list prices, not invoices.

Set up an org (admins)

1. Sign in to the console at https://app.box.stacktrace.ai.
2. Connect providers on the Providers page.
3. Create API keys for your team on the API keys page.

Then prepare the images your team uses, so their first sandboxes start fast, and check the setup:

stackbox image prepare python:3.13

stackbox doctor

An image that no provider prepared still runs. Its first start is slower.

Doctor image checks

stackbox doctor shows every recorded image and its preparation status on each connected provider. Failed, incomplete or missing preparations produce warnings without changing the exit code. An empty image inventory also produces a warning. Use stackbox doctor --image IMAGE to check one image. This command fails if no provider has prepared that image. Use stackbox image show IMAGE to inspect preparation errors. These checks read preparation records. They do not create sandboxes or run commands.

Cloudflare

Connect Cloudflare in the console with your account ID and API token. Stackbox deploys the bridge on your account. Setup progress and errors appear on the Providers page. You do not need Docker, Node.js or Wrangler on your machine.

Add an image through the normal preparation command:

stackbox image prepare python:3.13 -p cloudflare

Stackbox builds the image, updates the bridge and checks that a sandbox starts before marking it ready.

Harbor and the OpenSandbox SDKs

stackbox's API is OpenSandbox's. Harbor's opensandbox environment, the OpenSandbox SDKs and osb work unchanged. Point them at api.box.stacktrace.ai with your API key.

Configuration

stackbox auth login saves the API key in ~/.config/stackbox/config.toml, with mode 0600. STACKBOX_API_KEY and STACKBOX_URL override the file. The client sends the key only to that URL. It never holds a provider key.

Exit codes of the other commands: 0 when the command did what it says, 1 when the API refused or failed, and 2 for bad usage or no API key.

License

Apache-2.0. The hosted service is a separate, proprietary product.