stackbox 0.1.0__py3-none-any.whl

stackbox/vcr.py

@@ -0,0 +1,113 @@
+"""Push an image into Vercel Container Registry (VCR) with execd baked in.
+
+Vercel Sandbox boots only images in VCR (``ubuntu:24.04`` from Docker Hub returns
+"Image not found"). This builds ``FROM <image>`` plus OpenSandbox's execd, pushes it to
+``vcr.vercel.com/<team>/<project>/stackbox:<tag>``, and prints the reference to
+put in the backend's ``vercel_images`` map. Needs a local Docker daemon and
+VERCEL_TOKEN, VERCEL_TEAM_ID, VERCEL_PROJECT_ID. Credentials are never printed.
+
+Used by the Vercel backend's prepare step (and scripts/vercel_push_image.py).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+import httpx
+
+VCR_HOST = "vcr.vercel.com"
+REPOSITORY = "stackbox"
+API = "https://api.vercel.com"
+
+
+def scope() -> tuple[str, str, str]:
+    """(team slug, project name, temporary VCR token)."""
+    token = os.environ["VERCEL_TOKEN"]
+    team_id = os.environ["VERCEL_TEAM_ID"]
+    project_id = os.environ["VERCEL_PROJECT_ID"]
+    h = {"Authorization": f"Bearer {token}"}
+    with httpx.Client(timeout=30) as c:
+        team = c.get(f"{API}/v2/teams/{team_id}", headers=h)
+        team.raise_for_status()
+        project = c.get(
+            f"{API}/v9/projects/{project_id}", headers=h, params={"teamId": team_id}
+        )
+        project.raise_for_status()
+        minted = c.post(
+            f"{API}/projects/{project_id}/token",
+            headers=h,
+            params={"teamId": team_id},
+            json={"source": "vercel-cli"},
+        )
+        minted.raise_for_status()
+    return team.json()["slug"], project.json()["name"], minted.json()["token"]
+
+
+def docker_available() -> bool:
+    if shutil.which("docker") is None:
+        return False
+    return (
+        subprocess.run(["docker", "info"], capture_output=True, check=False).returncode
+        == 0
+    )
+
+
+def tag_for(image: str, execd: Path) -> str:
+    """Deterministic: the same image and execd always map to the same VCR tag."""
+    digest = hashlib.sha256(execd.read_bytes()).hexdigest()[:12]
+    return re.sub(r"[^a-zA-Z0-9_.-]", "-", image)[:80] + f"-execd-{digest}"
+
+
+def existing(image: str, execd: Path) -> str | None:
+    """The VCR reference for image + execd if it was pushed before, else None. No Docker."""
+    team, project, vcr_token = scope()
+    tag = tag_for(image, execd)
+    url = f"https://{VCR_HOST}/v2/{team}/{project}/{REPOSITORY}/manifests/{tag}"
+    with httpx.Client(timeout=30) as c:
+        r = c.head(
+            url,
+            auth=("oidc", vcr_token),
+            headers={
+                "Accept": "application/vnd.oci.image.manifest.v1+json, "
+                "application/vnd.docker.distribution.manifest.v2+json, "
+                "application/vnd.oci.image.index.v1+json"
+            },
+        )
+    return (
+        f"{VCR_HOST}/{team}/{project}/{REPOSITORY}:{tag}"
+        if r.status_code == 200
+        else None
+    )
+
+
+def push(image: str, execd: Path, *, quiet: bool = True) -> str:
+    """Build FROM image + execd, push to VCR, return the reference."""
+    tag = tag_for(image, execd)
+    team, project, vcr_token = scope()
+    ref = f"{VCR_HOST}/{team}/{project}/{REPOSITORY}:{tag}"
+    with tempfile.TemporaryDirectory() as ctx:
+        shutil.copy(execd, Path(ctx) / "execd")
+        (Path(ctx) / "Dockerfile").write_text(
+            f"FROM {image}\n"
+            "COPY execd /opt/opensandbox/execd\n"
+            "RUN chmod 755 /opt/opensandbox/execd\n"
+        )
+        subprocess.run(
+            ["docker", "build", "--platform", "linux/amd64", "-t", ref, ctx],
+            check=True,
+            capture_output=quiet,
+        )
+    subprocess.run(
+        ["docker", "login", VCR_HOST, "-u", "oidc", "--password-stdin"],
+        input=vcr_token.encode(),
+        check=True,
+        capture_output=True,
+    )
+    subprocess.run(["docker", "push", ref], check=True, capture_output=quiet)
+    return ref

stackbox-0.1.0.dist-info/METADATA

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: stackbox
+Version: 0.1.0
+Summary: One API for every sandbox provider: an OpenSandbox-compatible gateway that routes sandboxes across E2B, Modal, Daytona, Vercel and Cloudflare
+Keywords: sandbox,opensandbox,e2b,modal,daytona,vercel,cloudflare,agents
+Author: Stacktrace AI, Inc
+Author-email: Stacktrace AI, Inc <founders@stacktrace.ai>
+License-Expression: LicenseRef-Proprietary
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: fastapi>=0.162.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.14.3
+Requires-Dist: uvicorn>=0.54.0
+Requires-Dist: stackbox[e2b,modal,daytona,vercel] ; extra == 'all'
+Requires-Dist: daytona>=0.231.0 ; extra == 'daytona'
+Requires-Dist: e2b>=2.63.0 ; extra == 'e2b'
+Requires-Dist: aiohttp-socks>=0.12.0 ; extra == 'modal'
+Requires-Dist: modal>=1.6.3 ; extra == 'modal'
+Requires-Dist: python-socks>=3.2.1 ; extra == 'modal'
+Requires-Dist: vercel-sandbox>=0.11.0 ; extra == 'vercel'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://stacktrace.ai
+Provides-Extra: all
+Provides-Extra: daytona
+Provides-Extra: e2b
+Provides-Extra: modal
+Provides-Extra: vercel
+Description-Content-Type: text/markdown
+
+# 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
+
+```bash
+uv tool install "stackbox[all]"        # or: pip install "stackbox[all]"
+
+export E2B_API_KEY=...                 # any provider; `stackbox providers` lists them all
+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 their credentials;
+- 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** (`pip install opensandbox`; the snippet uses top-level `await`, as in Jupyter or `python -m asyncio`, and `examples/quickstart.py` is the same code as a script):
+
+```python
+from opensandbox import Sandbox
+from opensandbox.config import ConnectionConfig
+
+gateway = ConnectionConfig(domain="http://127.0.0.1:8090", protocol="https")
+sandbox = await Sandbox.create("ubuntu:24.04", connection_config=gateway)
+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
+gateway, and `protocol: https`. Then:
+
+```bash
+harbor run -c examples/harbor.yaml
+```
+
+## Routing
+
+Pick a default strategy with `[routing] strategy` or `serve --strategy`, and override it per
+request, OpenRouter-style:
+
+| Strategy | Picks |
+|---|---|
+| `balanced` (default) | the best mix of price and startup time |
+| `cost` | the lowest list price for what the provider would bill |
+| `latency` | the lowest learned time-to-sandbox for this image on this provider |
+| `priority` | backends in configured `priority` order |
+
+**Per-request preferences** go in headers (SDK: `ConnectionConfig(headers=…)`) or in sandbox
+metadata (Harbor: `kwargs.metadata`):
+
+| Header | Metadata key | Meaning |
+|---|---|---|
+| `X-Stackbox-Strategy: cost` | `stackbox.dev/strategy` | override the strategy |
+| `X-Stackbox-Providers: e2b,modal` | `stackbox.dev/providers` (`e2b.modal`) | only these providers; without a strategy, try them in this order |
+| `X-Stackbox-Max-Price: 0.10` | `stackbox.dev/max-price` | skip providers above this USD per sandbox-hour |
+| `X-Stackbox-Backend: e2b` | `stackbox.dev/backend` | pin to one provider, no fallback |
+
+**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 gateway 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
+
+| Command | What it does |
+|---|---|
+| `stackbox providers` | supported providers, list prices, plan limits, which you have set up, and live status |
+| `stackbox init` | write `stackbox.toml` for the providers in your environment |
+| `stackbox doctor` | per provider: SDK, credentials, API reachable, `execd`, image prepared; each failure comes with its fix |
+| `stackbox prepare IMAGE…` | build templates and image layers, push to Vercel's registry; `-p` limits to some providers |
+| `stackbox serve` | run the server (`--host`, `--port`, `--strategy`) |
+| `stackbox route [IMAGE]` | where a sandbox would go right now, and why (`--strategy`, `--providers`, `--max-price`, `--cpu`, `--memory`) |
+| `stackbox images [IMAGE]` | prepared images per provider |
+| `stackbox sandboxes` | sandboxes the running server holds, with provider and cost (`--all` includes ended ones) |
+| `stackbox placement ID` | where one sandbox went, every attempt, and its cost |
+| `stackbox usage` | sandbox-hours, vCPU-hours, GiB-hours and estimated cost per provider (`--since 24h`) |
+
+`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.
+
+`doctor` exits 0 when everything passes, 1 when some providers have problems, and 2 when nothing
+is usable.
+
+## Providers
+
+| Kind | Credentials | Images | Notes |
+|---|---|---|---|
+| `e2b` | `E2B_API_KEY` | any image; prepared as an E2B template with `execd` (about 45 s, once) | Firecracker; a template fixes vCPU and memory |
+| `modal` | `modal token set`, or `MODAL_TOKEN_ID` + `MODAL_TOKEN_SECRET` | any image; the `execd` layer is built once | gVisor; 1 vCPU = half a Modal core |
+| `daytona` | `DAYTONA_API_KEY` | any image, as a declarative image Daytona builds once and caches | the account memory quota is discovered automatically |
+| `vercel` | `VERCEL_TOKEN` + `VERCEL_TEAM_ID` + `VERCEL_PROJECT_ID` | Vercel's registry only; `prepare` pushes image + `execd` there (needs Docker once) | bills active CPU only; Hobby caps sandboxes at 45 min |
+| `cloudflare` | `CLOUDFLARE_BRIDGE_URL` + `CLOUDFLARE_BRIDGE_TOKEN` | fixed when the bridge is deployed | deploy the bridge Worker once (`bridges/cloudflare`); bills active CPU only |
+| `opensandbox` | `url` (+ `api_key`) in config | the server pulls them | your own OpenSandbox servers on Docker or Kubernetes |
+
+On hosted providers the gateway 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 gateway. 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.
+
+```toml
+[gateway]
+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):
+
+| Route | |
+|---|---|
+| `POST/GET /v1/sandboxes`, `GET/DELETE /v1/sandboxes/{id}` | create, list, get, delete |
+| `/v1/sandboxes/{id}/endpoints/{port}`, `…/renew-expiration`, … | forwarded to the provider; hosted providers implement endpoints and renew-expiration and return `501` for the rest |
+| `/v1/snapshots`, `/v1/templates` | `501 STACKBOX::UNSUPPORTED`; prepare images with `POST /v1/images` instead |
+
+**stackbox API:**
+
+| Route | |
+|---|---|
+| `GET /v1/providers`, `GET /v1/providers/{name}` | pricing, capacity (held, limit, learned quota), health, learned startup per image, prepared images, usage |
+| `GET /v1/route?image=…&strategy=…&providers=…&max_price=…&cpu=…&memory_gib=…` | where a sandbox would go right now, and why, for every provider (dry run) |
+| `GET /v1/placements/{sandbox_id}` | where a sandbox went, every attempt (outcome, error, duration), and its cost |
+| `GET /v1/images?image=…`, `POST /v1/images` `{image, providers?}` | prepared images per provider; prepare an image |
+| `GET /v1/usage?since=24h&until=…&group_by=provider\|sandbox` | sandbox-hours, vCPU-hours, GiB-hours, estimated cost |
+| `POST /v1/admin/reconcile` | run cleanup now |
+
+**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 gateway's managed tag.
+- **Ownership:** the tag holds a per-ledger instance id, so gateways 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 gateway 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 gateway, 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 gateway, versus 10/48 native (a per-trial registry-token rate
+    limit).
+  - Cloudflare: Harbor has no environment of its own; the gateway is how it gets there.
+
+Gateway 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.
+
+## Limits and next steps
+
+- **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
+
+```bash
+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.

stackbox-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+stackbox/__init__.py,sha256=neGMcLo9-dMvi3HswH6eBlZ7V7x5PDbDOz2J43r9gHY,184
+stackbox/__main__.py,sha256=S57F8tfuemIzn1W6P_Jmg2x_K3wXMdNP2dpxuM-ZNvk,34
+stackbox/app.py,sha256=zkt9rJuWhUlrjXAKKVhSFIcF5R5eLfe-NbYnytkrFAs,14772
+stackbox/backends/__init__.py,sha256=GNNOj-bJRGBFx6ynAfVizpszmTXZygWVq9nArlkI-x8,2959
+stackbox/backends/base.py,sha256=Y77uLfrkTxmlHjdix9k1mYBOl6uUmE_ddGGPuGTm3dk,6240
+stackbox/backends/cloudflare.py,sha256=Qp4jL_fSWfikIv47RavgUgJvujA8aRjXctwkE97LFLs,9326
+stackbox/backends/daytona.py,sha256=VO15Lbe-O6rhROUeaqpv8q0kcltLgjVAmj1Rzu4Q9mE,11088
+stackbox/backends/e2b.py,sha256=DcIaTOjyIDXkijxOaS0V3Y5NImm9MqPjMmd-cF5Xqq0,9409
+stackbox/backends/hosted.py,sha256=DR-AZYFPCRR2fUY_P_1Pnkcr0GUN2T2ZI6z_pAJO--M,19030
+stackbox/backends/modal.py,sha256=Xjsnng6N00jXbs3g-Z4-IzqfbzhnQ6sKCvm0LpB-VaM,6800
+stackbox/backends/opensandbox.py,sha256=L1R9ASd6DQWYYrzR--fwOM8Ol6MD43Ot5mYz8HSPrYU,5040
+stackbox/backends/vercel.py,sha256=7LbIpM8ZBXG8-UYu_V87T_UUlgbo0z0DXkO0ae-mCdw,11940
+stackbox/catalog.py,sha256=RAXafzlaPhEHfkOYN9GS8gkgAl0qFwpPzx-9px81reQ,5614
+stackbox/cli.py,sha256=8mm6WWj1kaKFg6b98i2i4J5DoZqeh9IeB6F2l4QyYww,30582
+stackbox/config.py,sha256=erBw48xNvYEbo3-O6r_aLjN2gEq7Y_Pqe5--CFs_FS0,10815
+stackbox/execd.py,sha256=69TFqCqbsf2u64EquxMnCsH3vyJf0_Lxm0hqdcM4L-A,4320
+stackbox/ledger.py,sha256=ZdEuKsRc7YIlCW5Ws8OWFNiX4T0pJgMZ9Fc3NgSFgk0,13370
+stackbox/router.py,sha256=cldED1i58r8yeMIliYKPwNOqwPZaUphS_KbIyc1SfEo,42432
+stackbox/vcr.py,sha256=Rg85Rh4GLl1e9-EjWpCM0U0ISqp93qR0lUvqboCimkE,3949
+stackbox-0.1.0.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+stackbox-0.1.0.dist-info/entry_points.txt,sha256=fWT1b6T4OzBgKLfNF-MVFLBn43x4GCSZns0-Ijs0-b4,44
+stackbox-0.1.0.dist-info/METADATA,sha256=-2sR-dmlcfp5I70R9mzFsHIFy2sM0g58Mnz8Xdn5p10,14321
+stackbox-0.1.0.dist-info/RECORD,,

stackbox-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.7
+Root-Is-Purelib: true
+Tag: py3-none-any

stackbox-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+stackbox = stackbox:main
+