stackbox

One OpenSandbox-compatible endpoint for E2B, Modal, Daytona, Vercel, Cloudflare and your own OpenSandbox servers. Each sandbox goes to the cheapest or fastest provider that can run it, quotas are pooled across accounts, and failures fail over without duplicates or leaked sandboxes.

Clients don't change. The stock OpenSandbox SDKs (Python, Go, Kotlin, TS, C#), the osb CLI, and Harbor's opensandbox environment all talk to it as if it were one OpenSandbox server.

Quickstart

uv tool install "stackbox[all]"        # or: pip install "stackbox[all]"

stackbox login                         # choose a provider, paste its key; checked, then saved
stackbox doctor                        # checks each provider end to end, says what to fix
stackbox prepare ubuntu:24.04          # makes the image fast to start on every provider
stackbox serve                         # http://127.0.0.1:8090

No config file is needed:

• providers are detected from stackbox login or their usual environment variables;
• prices and plan limits come from a built-in catalog;
• the execd binary each sandbox runs is downloaded automatically.

stackbox init writes a stackbox.toml when you want to customise.

Python with the stock OpenSandbox SDK. The same code is a script you can run: uv run examples/quickstart.py (uv installs the SDK for it), or pip install opensandbox first. The snippet uses top-level await, as in Jupyter or python -m asyncio:

from opensandbox import Sandbox
from opensandbox.config import ConnectionConfig

router = ConnectionConfig(domain="http://127.0.0.1:8090", protocol="https")
sandbox = await Sandbox.create("ubuntu:24.04", connection_config=router)
print((await sandbox.commands.run("echo hello")).logs.stdout[0].text)
await sandbox.kill()

Harbor (examples/harbor.yaml): set the environment to opensandbox, domain to the router, and protocol: https. Then:

harbor run -c examples/harbor.yaml

Routing

Pick a default strategy with [routing] strategy or serve --strategy, and override it per request, OpenRouter-style:

Per-request preferences go in headers (SDK: ConnectionConfig(headers=…)) or in sandbox metadata (Harbor: kwargs.metadata):

Why a sandbox goes where it does: stackbox route [IMAGE] (or GET /v1/route?image=…) lists every provider in order with its price, expected startup time and status, for example:

• next placement goes here;
• full: 5/5 (learned from provider refusals);
• not prepared; run stackbox prepare …;
• too expensive.

Errors carry the same per-provider reasons and a hint.

How the routing behaves:

• Learns startup time: the latency estimate is an average of observed creates per provider and image, weighted toward recent ones. It survives restarts, and each provider gets 3 measured starts before it can lose on its default estimate.
• Discovers quotas: a provider's quota refusal (Daytona's memory cap, E2B's rate limit, Modal's resource limits, Cloudflare having no instances to hand out) is not a failure.
  • The router caps that provider at its current count, growing the cap back by one every 15 s.
  • New creates spill to other providers or wait.
  • Refusals don't count toward the circuit breaker.
• Fails over only when it's safe:
  • A clean failure (nothing was created) moves on to the next provider.
  • An ambiguous one (timeout, 5xx) first checks the provider for the sandbox and adopts or deletes what it finds.
  • If the outcome can't be determined, it returns 503 STACKBOX::OUTCOME_UNKNOWN rather than risk a duplicate.
• Breaker and retries: a per-backend circuit breaker demotes a backend after repeated failures, and retries go to other backends first.

CLI

stackbox providers also shows live status (held/limit, placements) when a server is running.

Every command takes -c FILE, and the read commands take --json. Config is found in this order:

1. -c;
2. $STACKBOX_CONFIG;
3. ./stackbox.toml;
4. auto-detection from credentials.

A config file lists the providers to use, so a provider you log in to later isn't used until it's in the file. stackbox login offers to add it, and stackbox init --add adds every one that's missing.

Credentials. stackbox login saves them in ~/.config/stackbox/credentials.toml ($XDG_CONFIG_HOME, or $STACKBOX_CREDENTIALS), readable only by you. Each provider's own environment variables (E2B_API_KEY, VERCEL_TOKEN, …) still work and take precedence, which is what CI should use:

echo "$E2B_API_KEY" | stackbox login e2b --with-token

printf 'VERCEL_TOKEN=%s\nVERCEL_TEAM_ID=%s\nVERCEL_PROJECT_ID=%s\n' "$TOKEN" "$TEAM" "$PROJECT" | stackbox login vercel --with-token

doctor exits 0 when everything passes, 1 when some providers have problems, and 2 when nothing is usable.

Providers

On hosted providers the router emulates the OpenSandbox lifecycle on the provider's SDK and runs OpenSandbox's execd in every sandbox, with a per-sandbox token. GET /sandboxes/{id}/endpoints/44772 returns the provider's URL and the headers to send. Command and file traffic goes from the client to the sandbox, not through the router. Cloudflare is the exception: it goes through the bridge Worker.

Configuration

Every field is optional except kind; the provider catalog fills in the rest. See examples/all-providers.toml for every provider, and stackbox init for a starter.

[server]
api_key = "env:STACKBOX_API_KEY"   # required to listen beyond 127.0.0.1

[routing]
strategy = "balanced"

[[backends]]
kind = "e2b"
max_active = 50          # your plan's concurrency

[[backends]]
kind = "modal"
priority = 10

• Secrets: "env:NAME" values (or "env:A|B") are read from the environment, so secrets stay out of config files.
• Common backend fields:
  • max_active (concurrency);
  • priority;
  • cost_per_vcpu_hour and cost_per_gib_hour;
  • cpu_billed_fraction, for providers that bill only active CPU;
  • max_timeout_s;
  • default_cpu and default_memory_gib;
  • auto_prepare;
  • execd_path, if you'd rather supply execd yourself.

HTTP API

Hosted at https://stackbox.stacktrace.dev, or wherever you run stackbox serve. Every route except GET /health needs the API key in OPEN-SANDBOX-API-KEY.

OpenSandbox API (what the SDKs, Harbor and osb use, unchanged):

stackbox API:

Errors are JSON: {code: "STACKBOX::…", message, details, hint}. The message includes the hint, since SDKs show only the message. SANDBOX::NOT_FOUND keeps OpenSandbox's standard code.

Reliability

• Ledger: a SQLite ledger records intent before every upstream create, and every attempt's outcome.
• Reconciler: runs periodically and on POST /v1/admin/reconcile:
  • deletes orphans from ambiguous creates;
  • expires sandboxes that vanished upstream;
  • deletes leaked sandboxes carrying this router's managed tag.
• Ownership: the tag holds a per-ledger instance id, so routers sharing an account never touch each other's sandboxes.

Verified

All of these ran on real accounts with Harbor trials (an oracle agent, ubuntu:24.04, 1 vCPU, 2 GiB). Full write-ups: bench/LIVE.md and bench/LIVE-MORE.md; the local fault-injection benchmark is in bench/RESULTS.md.

• Reliability: every router arm passed 48/48 with no leaked sandboxes. That covers E2B, Modal, Daytona, Vercel, Cloudflare, cost and latency routing, and quota pooling.
• Strategy decides placement: cost chose E2B, 28% cheaper than Modal. latency chose the fastest-starting provider and followed it as providers sped up and slowed down.
• Quotas:
  • Pooling two 4-sandbox quotas: 36 s, versus 69 s on one provider.
  • Daytona's 10 GiB account quota: 67–71 s through the router, versus 199 s with Harbor's own Daytona environment; 40–56 s with E2B taking the overflow.
• Against Harbor's own provider environments:
  • E2B: 14% faster and 16% cheaper, traced to Harbor's E2B file transfers.
  • Vercel: 48/48 through the router, versus 10/48 native (a per-trial registry-token rate limit).
  • Cloudflare: Harbor has no environment of its own; the router is how it gets there.

Router create p50: Modal 0.6–0.8 s, Vercel 0.9 s, E2B 1.1–1.4 s, Cloudflare 1.5 s, Daytona 2.8–3.5 s.

Two public benchmarks, with their setup and caveats:

• Terminal-Bench 2.0 (bench/TB2.md): 12 tasks with Harbor's oracle agent, 12/12 on every arm. stackbox cost matched Harbor's best environment (E2B: 104 s vs 105 s). balanced took 139 s where Harbor's Daytona environment took 377 s, queued behind the account quota.
• ComputeSDK Burst TTI (bench/computesdk/README.md): within an account's limits a provider is faster used directly (stackbox adds 0.3 s on Modal, 2 s on E2B, 5 s on Daytona to time to first command). At 100 sandboxes at once stackbox completed all of them, while E2B, Daytona and Vercel used directly on our accounts completed 39%, 30% and 16%.

Limits and next steps

• Startup costs more through stackbox than direct, mostly on E2B and Daytona: starting execd and the first commands in a freshly started custom image. Next: snapshot a running execd into the template where the provider allows it (bench/computesdk/README.md).
• latency explores each provider for each image, so a run with many distinct images spends most placements exploring. Next: share startup estimates across images on the same provider.
• A single command streaming for about six minutes lost its connection on E2B (not yet explained; see bench/TB2.md).
• Latency routing learns startup time, not task runtime. It picked Vercel for its fast starts, but Vercel trials ran longer. Next: learn per-provider runtime from completed sandboxes.
• Hosted providers lack some OpenSandbox features: no egress sidecar (network policy), pause/resume or snapshots. Only E2B exposes ports other than execd's, and Modal can't extend a running sandbox.
• Cost is an estimate from list prices and allocated resources, not invoices. Active-CPU billing is approximated with cpu_billed_fraction.
• Cloudflare adds a hop: execd traffic goes through the bridge Worker, at about 165 ms per command versus about 110 ms elsewhere.
• Listing doesn't scale yet: the list endpoint queries every backend on each call.
• Later: a Kubernetes backend, region and GPU matching, and per-tenant quotas.

Development

git clone https://github.com/stacktrace-ai/stackbox && cd stackbox
uv sync --all-extras
uv run pytest -q                                  # all tests run against in-memory fakes
uv run ruff check src tests bench scripts examples && uv run ruff format

Contributor guidelines and the developer-experience principles are in CLAUDE.md. Releases ship by pushing a v<version> tag; see docs/releases/ and the release-stackbox skill.

License

Apache License 2.0. See LICENSE and NOTICE.