stackbox 0.1.0__py3-none-any.whl

stackbox/cli.py

@@ -0,0 +1,873 @@
+"""The `stackbox` command line.
+
+  stackbox providers            what is supported, what you have set up, prices
+  stackbox init                 write stackbox.toml for the providers you have
+  stackbox doctor               check every provider end to end, with fixes
+  stackbox prepare IMAGE        make IMAGE fast to start everywhere
+  stackbox serve                run the gateway
+  stackbox route IMAGE          where a sandbox would go right now, and why
+  stackbox images               prepared images per provider
+  stackbox sandboxes            what the running server holds
+  stackbox placement ID         where one sandbox went, its attempts and cost
+  stackbox usage                sandbox time and estimated cost per provider
+
+Config: -c FILE, else $STACKBOX_CONFIG, else ./stackbox.toml, else providers
+are auto-detected from credentials in the environment.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from stackbox import catalog
+from stackbox.config import (
+    CONFIG_FILE,
+    ConfigError,
+    RouterConfig,
+    resolve_config,
+)
+
+DEFAULT_PORT = 8090
+DEFAULT_IMAGE = "ubuntu:24.04"
+OK, FAIL, WARN = "✓", "✗", "!"
+
+
+def _version() -> str:
+    from stackbox import __version__
+
+    return __version__
+
+
+def _print_json(data: Any) -> None:
+    print(json.dumps(data, indent=2, default=str))
+
+
+def _table(rows: list[list[str]], headers: list[str]) -> str:
+    widths = [
+        max(len(str(x)) for x in col) for col in zip(headers, *rows, strict=False)
+    ]
+    line = lambda r: "  ".join(str(x).ljust(w) for x, w in zip(r, widths, strict=False))
+    return "\n".join([line(headers), *(line(r) for r in rows)])
+
+
+def _load(args: argparse.Namespace) -> tuple[RouterConfig, str]:
+    return resolve_config(getattr(args, "config", None))
+
+
+def _price(p: catalog.Provider) -> str:
+    return f"${p.price_1vcpu_2gib():.3f}/h"
+
+
+# ------------------------------------------------------------------ providers
+def cmd_providers(args: argparse.Namespace) -> int:
+    configured: set[str] = set()
+    try:
+        cfg, _ = _load(args)
+        configured = {b.kind for b in cfg.backends}
+    except ConfigError:
+        pass
+    rows, out = [], []
+    for p in catalog.PROVIDERS.values():
+        status = (
+            "in use"
+            if p.kind in configured
+            else ("credentials found, not in config" if p.detected() else "not set up")
+        )
+        if not p.installed():
+            status += f" (install extra: {p.extra})"
+        life = p.defaults.get("max_timeout_s", 0)
+        rows.append(
+            [
+                p.kind,
+                p.label,
+                status,
+                _price(p),
+                f"{life // 3600} h" if life >= 3600 else f"{life // 60} min",
+                p.missing_credentials(),
+            ]
+        )
+        out.append(
+            {
+                "kind": p.kind,
+                "label": p.label,
+                "status": status,
+                "usd_per_hour_1vcpu_2gib": round(p.price_1vcpu_2gib(), 4),
+                "max_lifetime_s": life,
+                "credentials": [list(g) for g in p.credentials],
+                "extra": p.extra,
+                "signup": p.signup,
+                "pricing": p.pricing,
+                "notes": p.notes,
+            }
+        )
+    live = _try_get(args, "/v1/providers")
+    if live is not None:
+        by_kind = {p["kind"]: p for p in live["items"]}
+        for row, item in zip(rows, out, strict=True):
+            lp = by_kind.get(item["kind"])
+            if lp:
+                cap = lp["capacity"]
+                item["live"] = lp
+                row[2] = (
+                    f"{lp['status']}, {cap['held']}/{cap['limit']} held, {lp['placements']} placed"
+                )
+    if args.json:
+        _print_json(out)
+        return 0
+    print(
+        _table(
+            rows,
+            ["KIND", "PROVIDER", "STATUS", "LIST PRICE*", "MAX LIFE", "CREDENTIALS"],
+        )
+    )
+    if live is not None:
+        print(f"\nLive status from {_server(args)[0]}.")
+    print(
+        "\n* 1 vCPU + 2 GiB per hour, list price; `stackbox providers --json` for links."
+    )
+    if not any(p.detected() for p in catalog.PROVIDERS.values()) and not configured:
+        print("\nNo provider is set up yet. For example:")
+        print("  export E2B_API_KEY=...        # https://e2b.dev/dashboard?tab=keys")
+        print("  stackbox doctor")
+    return 0
+
+
+# ---------------------------------------------------------------------- init
+def cmd_init(args: argparse.Namespace) -> int:
+    path = Path(args.output)
+    if path.exists() and not args.force:
+        print(f"{path} already exists; use --force to overwrite.", file=sys.stderr)
+        return 1
+    found = catalog.detected()
+    lines = [
+        "# stackbox config. Every field is optional except kind; unset fields come",
+        "# from the built-in provider catalog (list prices, plan limits, sizes).",
+        "# Docs: README.md. Check it with: stackbox doctor",
+        "",
+        "[gateway]",
+        "# Clients send this in the OPEN-SANDBOX-API-KEY header. Required unless you only",
+        "# listen on 127.0.0.1.",
+        '# api_key = "env:STACKBOX_API_KEY"',
+        "",
+        "[routing]",
+        'strategy = "balanced"   # priority | cost | latency | balanced',
+        "",
+    ]
+    for p in catalog.PROVIDERS.values():
+        on = p in found
+        prefix = "" if on else "# "
+        lines.append(
+            f"# {p.label}: {_price(p)} for 1 vCPU + 2 GiB. {p.notes}."
+            + ("" if on else f" Needs {p.missing_credentials()}.")
+        )
+        lines.append(f"{prefix}[[backends]]")
+        lines.append(f'{prefix}kind = "{p.kind}"')
+        lines.append("")
+    path.write_text("\n".join(lines))
+    print(
+        f"Wrote {path} with {len(found)} provider(s): {', '.join(p.kind for p in found) or 'none yet'}."
+    )
+    if not found:
+        print(
+            "Set a provider's credentials and uncomment its block (see `stackbox providers`)."
+        )
+    print("\nNext:")
+    print("  stackbox doctor                 # check everything works")
+    print(f"  stackbox prepare {DEFAULT_IMAGE}    # make your image fast to start")
+    print("  stackbox serve")
+    return 0
+
+
+# -------------------------------------------------------------------- doctor
+async def _doctor(cfg: RouterConfig, image: str | None) -> list[dict[str, Any]]:
+    from stackbox import execd as execd_mod
+    from stackbox import ledger as L
+    from stackbox.backends import MANAGED_KEY, make_backend
+    from stackbox.backends.hosted import HostedBackend
+
+    ledger = L.Ledger(cfg.gateway.db_path)
+    results: list[dict[str, Any]] = []
+
+    def check(
+        backend: str, name: str, ok: bool | None, detail: str, fix: str = ""
+    ) -> None:
+        results.append(
+            {"backend": backend, "check": name, "ok": ok, "detail": detail, "fix": fix}
+        )
+
+    execd_checked: str | None = None
+    for bcfg in cfg.backends:
+        p = catalog.PROVIDERS.get(bcfg.kind)
+        if p is not None and not p.installed():
+            check(
+                bcfg.name,
+                "SDK installed",
+                False,
+                f"python module {p.module} not found",
+                f"uv sync --extra {p.extra}   (or: pip install 'stackbox[{p.extra}]')",
+            )
+            continue
+        if (
+            p is not None
+            and p.credentials
+            and not p.detected()
+            and bcfg.kind != "cloudflare"
+        ):
+            check(
+                bcfg.name,
+                "credentials",
+                False,
+                f"{p.missing_credentials()} not set",
+                f"export {p.missing_credentials().split(' + ')[0]}=...   ({p.signup})",
+            )
+            continue
+        try:
+            backend = make_backend(bcfg, cfg.gateway, ledger)
+        except Exception as exc:  # noqa: BLE001 - reported
+            check(bcfg.name, "config", False, str(exc))
+            continue
+        t0 = time.monotonic()
+        try:
+            live = await asyncio.wait_for(
+                backend.list_sandboxes({MANAGED_KEY: backend.instance_id}), 30
+            )
+            check(
+                bcfg.name,
+                "API reachable",
+                True,
+                f"{len(live)} sandbox(es) of this gateway running; {1000 * (time.monotonic() - t0):.0f} ms",
+            )
+        except Exception as exc:  # noqa: BLE001 - reported
+            check(
+                bcfg.name,
+                "API reachable",
+                False,
+                f"{type(exc).__name__}: {str(exc)[:200]}",
+                "check the credentials and network access to the provider",
+            )
+            await backend.aclose()
+            continue
+        if isinstance(backend, HostedBackend) and bcfg.kind != "cloudflare":
+            key = bcfg.execd_path or "cached"
+            if execd_checked != key:
+                try:
+                    path = execd_mod.ensure(bcfg.execd_path)
+                    check(
+                        bcfg.name,
+                        "execd",
+                        True,
+                        f"{path} ({path.stat().st_size / 1e6:.1f} MB)",
+                    )
+                    execd_checked = key
+                except Exception as exc:  # noqa: BLE001 - reported
+                    check(
+                        bcfg.name,
+                        "execd",
+                        False,
+                        str(exc)[:200],
+                        "set execd_path to a local copy of the opensandbox/execd binary",
+                    )
+        if image:
+            support = backend.image_support(image, None, None)
+            for task in getattr(backend, "_preparing", {}).values():
+                task.cancel()  # doctor only reports; it does not start builds
+            rec = ledger.get_image(bcfg.name, image)
+            if support == "ready":
+                check(bcfg.name, f"image {image}", True, "prepared")
+            elif support == "cold":
+                check(
+                    bcfg.name,
+                    f"image {image}",
+                    None,
+                    "not prepared; the first sandbox will include an image build",
+                    f"stackbox prepare {image}",
+                )
+            else:
+                why = (
+                    f" (last attempt failed: {rec.error})" if rec and rec.error else ""
+                )
+                check(
+                    bcfg.name,
+                    f"image {image}",
+                    False,
+                    f"not prepared; this provider can't run it until it is{why}",
+                    f"stackbox prepare {image} --provider {bcfg.name}",
+                )
+        await backend.aclose()
+    return results
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    try:
+        cfg, source = _load(args)
+    except ConfigError as exc:
+        print(f"{FAIL} config: {exc}", file=sys.stderr)
+        return 2
+    results = asyncio.run(_doctor(cfg, args.image))
+    if args.json:
+        _print_json({"config": source, "checks": results})
+    else:
+        print(f"config: {source}\n")
+        last = None
+        for r in results:
+            if r["backend"] != last:
+                if last is not None:
+                    print()
+                print(r["backend"])
+                last = r["backend"]
+            mark = OK if r["ok"] else (WARN if r["ok"] is None else FAIL)
+            print(f"  {mark} {r['check']}: {r['detail']}")
+            if r["fix"] and not r["ok"]:
+                print(f"      fix: {r['fix']}")
+        unset = [
+            p
+            for p in catalog.PROVIDERS.values()
+            if p.kind not in {b.kind for b in cfg.backends}
+        ]
+        if unset:
+            print(
+                "\nNot configured: "
+                + ", ".join(p.kind for p in unset)
+                + "  (see `stackbox providers`)"
+            )
+    failed = [r for r in results if r["ok"] is False]
+    usable = {r["backend"] for r in results} - {r["backend"] for r in failed}
+    if not args.json:
+        print(
+            f"\n{len(usable)} of {len(cfg.backends)} provider(s) ready"
+            + ("" if not failed else f"; {len(failed)} problem(s) above")
+        )
+        fixes = []
+        for r in results:
+            if r["ok"] is not True and r["fix"]:
+                fix = r["fix"].split(" --provider ")[
+                    0
+                ]  # one prepare covers every provider
+                if fix not in fixes:
+                    fixes.append(fix)
+        if fixes:
+            print("\nNext:")
+            for fix in fixes:
+                print(f"  {fix}")
+        elif not failed:
+            print("\nNext: stackbox serve")
+    return 0 if not failed else (1 if usable else 2)
+
+
+# ------------------------------------------------------------------- prepare
+def cmd_prepare(args: argparse.Namespace) -> int:
+    from stackbox import ledger as L
+    from stackbox.backends import make_backend
+
+    try:
+        cfg, _ = _load(args)
+    except ConfigError as exc:
+        print(f"{FAIL} {exc}", file=sys.stderr)
+        return 2
+    ledger = L.Ledger(cfg.gateway.db_path)
+    names = args.provider or [b.name for b in cfg.backends if b.kind != "opensandbox"]
+    unknown = [n for n in names if n not in {b.name for b in cfg.backends}]
+    if unknown:
+        print(f"{FAIL} unknown provider(s): {', '.join(unknown)}", file=sys.stderr)
+        return 2
+
+    async def run() -> list[dict[str, Any]]:
+        backends = [make_backend(cfg.backend(n), cfg.gateway, ledger) for n in names]
+        jobs = [(b, img) for b in backends for img in args.images]
+        if not args.json:
+            print(f"Preparing {', '.join(args.images)} on {', '.join(names)} …")
+        results = await asyncio.gather(
+            *(b.prepare(img) for b, img in jobs), return_exceptions=True
+        )
+        out = []
+        for (b, img), r in zip(jobs, results, strict=True):
+            if isinstance(r, BaseException):
+                out.append(
+                    {"backend": b.name, "image": img, "ok": False, "error": f"{r}"}
+                )
+            else:
+                out.append({"ok": True, **r})
+        for b in backends:
+            await b.aclose()
+        return out
+
+    out = asyncio.run(run())
+    if args.json:
+        _print_json(out)
+    else:
+        for r in out:
+            if r["ok"]:
+                took = (
+                    f" in {r['prepare_s']} s" if r.get("prepare_s") is not None else ""
+                )
+                print(f"  {OK} {r['backend']}: {r['image']} ready{took}")
+            else:
+                print(f"  {FAIL} {r['backend']}: {r['image']}: {r['error']}")
+    return 0 if all(r["ok"] for r in out) else 1
+
+
+# ---------------------------------------------------------------------- rank
+def cmd_route(args: argparse.Namespace) -> int:
+    from stackbox import ledger as L
+    from stackbox.backends import make_backend
+    from stackbox.router import PlacementError, Request, Router, parse_preferences
+
+    try:
+        cfg, _ = _load(args)
+    except ConfigError as exc:
+        print(f"{FAIL} {exc}", file=sys.stderr)
+        return 2
+    try:
+        strategy, providers, max_price = parse_preferences(
+            {
+                k: v
+                for k, v in {
+                    "x-stackbox-strategy": args.strategy,
+                    "x-stackbox-providers": args.providers,
+                    "x-stackbox-max-price": args.max_price,
+                }.items()
+                if v
+            },
+            {},
+        )
+    except PlacementError as exc:
+        print(f"{FAIL} {exc} ({exc.hint})", file=sys.stderr)
+        return 2
+    ledger = L.Ledger(cfg.gateway.db_path)
+
+    async def run() -> list[dict[str, Any]]:
+        backends = {b.name: make_backend(b, cfg.gateway, ledger) for b in cfg.backends}
+        for b in backends.values():
+            b.cfg.auto_prepare = False  # route only looks
+        router = Router(cfg, ledger, backends)
+        try:
+            return router.explain(
+                Request(
+                    args.image, args.cpu, args.memory, strategy, providers, max_price
+                )
+            )
+        finally:
+            for b in backends.values():
+                await b.aclose()
+
+    rows = asyncio.run(run())
+    shown = strategy or cfg.routing.strategy
+    if args.json:
+        _print_json({"image": args.image, "strategy": shown, "items": rows})
+        return 0
+    print(f"strategy: {shown}   image: {args.image}\n")
+    table = [
+        [
+            str(r["rank"]) if r["rank"] else "-",
+            r["backend"],
+            f"${r['price_per_hour']:.3f}/h"
+            if r.get("price_per_hour") is not None
+            else "",
+            f"{r['expected_startup_s']:.1f} s"
+            if r.get("expected_startup_s") is not None
+            else "",
+            r["status"],
+        ]
+        for r in rows
+    ]
+    print(_table(table, ["#", "PROVIDER", "PRICE", "STARTUP", "STATUS"]))
+    return 0
+
+
+def cmd_images(args: argparse.Namespace) -> int:
+    from stackbox import ledger as L
+
+    try:
+        cfg, _ = _load(args)
+    except ConfigError as exc:
+        print(f"{FAIL} {exc}", file=sys.stderr)
+        return 2
+    rows = [
+        {
+            "provider": i["backend"],
+            **{k: i[k] for k in ("image", "status", "ref", "error")},
+        }
+        for i in L.Ledger(cfg.gateway.db_path).images()
+        if not args.image or i["image"] == args.image
+    ]
+    if args.json:
+        _print_json({"items": rows})
+        return 0
+    if not rows:
+        print(
+            f"No prepared images yet. Run: stackbox prepare {args.image or DEFAULT_IMAGE}"
+        )
+        return 0
+    print(
+        _table(
+            [
+                [
+                    r["image"],
+                    r["provider"],
+                    r["status"],
+                    (r["error"] or r["ref"] or "")[:70],
+                ]
+                for r in sorted(rows, key=lambda r: (r["image"], r["provider"]))
+            ],
+            ["IMAGE", "PROVIDER", "STATUS", "REF / ERROR"],
+        )
+    )
+    return 0
+
+
+# ------------------------------------------------- talking to a running server
+def _server(args: argparse.Namespace) -> tuple[str, dict[str, str]]:
+    url = (
+        args.url or os.environ.get("STACKBOX_URL") or f"http://127.0.0.1:{DEFAULT_PORT}"
+    ).rstrip("/")
+    key = os.environ.get("STACKBOX_API_KEY")
+    if key is None:
+        try:
+            key = _load(args)[0].gateway.api_key
+        except ConfigError:
+            key = None
+    return url, ({"OPEN-SANDBOX-API-KEY": key} if key else {})
+
+
+def _try_get(args: argparse.Namespace, path: str) -> Any | None:
+    """GET from a running server, or None if none is reachable (for optional live info)."""
+    import httpx
+
+    url, headers = _server(args)
+    try:
+        r = httpx.get(f"{url}{path}", headers=headers, timeout=1.5)
+        return r.json() if r.status_code == 200 else None
+    except (httpx.HTTPError, ValueError):
+        return None
+
+
+def _get(
+    args: argparse.Namespace, path: str, params: dict[str, Any] | None = None
+) -> Any:
+    import httpx
+
+    url, headers = _server(args)
+    try:
+        r = httpx.get(f"{url}{path}", headers=headers, params=params, timeout=10)
+    except httpx.HTTPError as exc:
+        raise SystemExit(
+            f"{FAIL} can't reach the gateway at {url} ({type(exc).__name__}). "
+            "Is `stackbox serve` running? Use --url for another address."
+        ) from exc
+    if r.status_code == 401:
+        raise SystemExit(f"{FAIL} {url} rejected the API key; set STACKBOX_API_KEY.")
+    if r.status_code >= 400:
+        try:
+            body = r.json()
+            raise SystemExit(f"{FAIL} {body.get('message', r.text)}")
+        except ValueError:
+            r.raise_for_status()
+    return r.json()
+
+
+def _age(iso: str | None) -> str:
+    if not iso:
+        return ""
+    import datetime as dt
+
+    secs = time.time() - dt.datetime.fromisoformat(iso).timestamp()
+    return f"{secs / 60:.0f} min" if secs < 5400 else f"{secs / 3600:.1f} h"
+
+
+def cmd_sandboxes(args: argparse.Namespace) -> int:
+    rows = [
+        r
+        for r in _get(args, "/v1/usage", {"group_by": "sandbox"})["sandboxes"]
+        if args.all or r["state"] in ("provisioning", "active", "unknown")
+    ]
+    if args.json:
+        _print_json({"items": rows})
+        return 0
+    if not rows:
+        print("No sandboxes." + ("" if args.all else " (--all includes ended ones)"))
+        return 0
+    print(
+        _table(
+            [
+                [
+                    r["id"],
+                    r["provider"] or "-",
+                    r["state"],
+                    r["image"] or "",
+                    _age(r["requested_at"]),
+                    f"${r['est_cost_usd']:.4f}",
+                ]
+                for r in rows
+            ],
+            ["ID", "PROVIDER", "STATE", "IMAGE", "AGE", "EST. COST"],
+        )
+    )
+    return 0
+
+
+def cmd_placement(args: argparse.Namespace) -> int:
+    p = _get(args, f"/v1/placements/{args.id}")
+    if args.json:
+        _print_json(p)
+        return 0
+    print(f"sandbox   {p['id']}")
+    print(
+        f"provider  {p['provider'] or '-'}   state: {p['state']}   image: {p['image']}"
+    )
+    print(
+        f"timing    queued {p['queued_s'] or 0:.2f} s, create {p['create_s'] or 0:.2f} s, "
+        f"ran {p['seconds']:.0f} s"
+    )
+    print(f"cost      ${p['est_cost_usd']:.6f} (estimate, list price)")
+    if p["last_error"]:
+        print(f"note      {p['last_error']}")
+    print("\nattempts:")
+    print(
+        _table(
+            [
+                [
+                    a["provider"],
+                    a["outcome"] or "in progress",
+                    f"{a['duration_s']:.2f} s" if a["duration_s"] is not None else "",
+                    (a["error"] or "")[:80],
+                ]
+                for a in p["attempts"]
+            ],
+            ["PROVIDER", "OUTCOME", "TOOK", "ERROR"],
+        )
+    )
+    return 0
+
+
+def cmd_usage(args: argparse.Namespace) -> int:
+    u = _get(args, "/v1/usage", {"since": args.since, "group_by": "provider"})
+    if args.json:
+        _print_json(u)
+        return 0
+    rows = [
+        [
+            name,
+            str(v["sandboxes"]),
+            f"{v['sandbox_hours']:.2f}",
+            f"{v['vcpu_hours']:.2f}",
+            f"{v['gib_hours']:.2f}",
+            f"${v['est_cost_usd']:.4f}",
+        ]
+        for name, v in sorted(u["providers"].items())
+    ]
+    t = u["totals"]
+    rows.append(
+        [
+            "total",
+            str(t["sandboxes"]),
+            f"{t['sandbox_hours']:.2f}",
+            f"{t['vcpu_hours']:.2f}",
+            f"{t['gib_hours']:.2f}",
+            f"${t['est_cost_usd']:.4f}",
+        ]
+    )
+    print(f"since {u['since'] or 'the start of the ledger'}\n")
+    print(
+        _table(
+            rows, ["PROVIDER", "SANDBOXES", "SANDBOX-H", "VCPU-H", "GIB-H", "EST. COST"]
+        )
+    )
+    print(f"\n{u['note']}.")
+    return 0
+
+
+# --------------------------------------------------------------------- serve
+def cmd_serve(args: argparse.Namespace) -> int:
+    import uvicorn
+
+    from stackbox.app import create_app
+
+    try:
+        cfg, source = _load(args)
+    except ConfigError as exc:
+        print(f"{FAIL} {exc}", file=sys.stderr)
+        return 2
+    if args.strategy:
+        cfg.routing.strategy = args.strategy
+    public = args.host not in ("127.0.0.1", "localhost", "::1")
+    if public and not cfg.gateway.api_key:
+        print(
+            f"{FAIL} refusing to listen on {args.host} without an API key: anyone who can reach "
+            "it could create sandboxes on your accounts.\n"
+            '  Set [gateway] api_key = "env:STACKBOX_API_KEY" in the config, or '
+            "export STACKBOX_API_KEY when using auto-detection.",
+            file=sys.stderr,
+        )
+        return 2
+    base = f"http://{args.host}:{args.port}"
+    print(f"stackbox {_version()}   config: {source}")
+    for b in cfg.backends:
+        p = catalog.PROVIDERS.get(b.kind)
+        label = p.label if p else b.kind
+        price = b.cost_per_vcpu_hour * b.cpu_billed_fraction + 2 * b.cost_per_gib_hour
+        print(
+            f"  {OK} {b.name:<11} {label:<22} ${price:.3f}/h for 1 vCPU + 2 GiB   max {b.max_active} at once"
+        )
+    print(f"  strategy: {cfg.routing.strategy}   ledger: {cfg.gateway.db_path}")
+    print(
+        f"\nListening on {base}"
+        + ("" if cfg.gateway.api_key else "   (no API key: local use only)")
+    )
+    print("Point any OpenSandbox client at it, e.g.:")
+    print(f'  Python  ConnectionConfig(domain="{base}", protocol="https")')
+    print(
+        f"  Harbor  environment: {{type: opensandbox, kwargs: {{domain: {base}, protocol: https}}}}\n"
+    )
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s"
+    )
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    uvicorn.run(create_app(cfg), host=args.host, port=args.port, log_level="warning")
+    return 0
+
+
+# ---------------------------------------------------------------------- main
+def build_parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "-c",
+        "--config",
+        default=argparse.SUPPRESS,
+        help=f"config file (default: $STACKBOX_CONFIG, ./{CONFIG_FILE}, or auto-detect)",
+    )
+    parser = argparse.ArgumentParser(
+        prog="stackbox",
+        description="One OpenSandbox-compatible endpoint for E2B, Modal, Daytona, Vercel, "
+        "Cloudflare and your own OpenSandbox servers.",
+        parents=[common],
+        epilog="Start with: stackbox providers, then stackbox doctor.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {_version()}")
+    # Before subcommands existed, `--host/--port` with no command meant serve.
+    parser.add_argument("--host", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+    parser.add_argument(
+        "--port", type=int, default=argparse.SUPPRESS, help=argparse.SUPPRESS
+    )
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    p = sub.add_parser(
+        "providers",
+        parents=[common],
+        help="supported providers, prices, what you have set up, and live status",
+    )
+    p.add_argument("--url", help="server to read live status from (if running)")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(fn=cmd_providers)
+
+    p = sub.add_parser(
+        "init",
+        parents=[common],
+        help=f"write ./{CONFIG_FILE} for the providers in your environment",
+    )
+    p.add_argument("-o", "--output", default=CONFIG_FILE)
+    p.add_argument("--force", action="store_true", help="overwrite an existing file")
+    p.set_defaults(fn=cmd_init)
+
+    p = sub.add_parser(
+        "doctor",
+        parents=[common],
+        help="check credentials, connectivity, execd and images per provider",
+    )
+    p.add_argument(
+        "--image",
+        default=DEFAULT_IMAGE,
+        help=f"image to check (default {DEFAULT_IMAGE})",
+    )
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(fn=cmd_doctor)
+
+    p = sub.add_parser(
+        "prepare", parents=[common], help="make images fast to start on every provider"
+    )
+    p.add_argument("images", nargs="+", metavar="IMAGE")
+    p.add_argument(
+        "-p", "--provider", action="append", help="only these providers (repeatable)"
+    )
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(fn=cmd_prepare)
+
+    p = sub.add_parser("serve", parents=[common], help="run the gateway")
+    p.add_argument("--host", default="127.0.0.1")
+    p.add_argument("--port", type=int, default=DEFAULT_PORT)
+    p.add_argument("--strategy", choices=["priority", "cost", "latency", "balanced"])
+    p.set_defaults(fn=cmd_serve)
+
+    p = sub.add_parser(
+        "route",
+        parents=[common],
+        help="where a sandbox for IMAGE would go right now, and why",
+    )
+    p.add_argument("image", nargs="?", default=DEFAULT_IMAGE)
+    p.add_argument("--cpu", type=float, help="vCPUs requested")
+    p.add_argument("--memory", type=float, help="GiB requested")
+    p.add_argument("--strategy", choices=["priority", "cost", "latency", "balanced"])
+    p.add_argument("--providers", help="allow-list, in order: e2b,modal")
+    p.add_argument("--max-price", help="USD per sandbox-hour")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(fn=cmd_route)
+
+    p = sub.add_parser("images", parents=[common], help="prepared images per provider")
+    p.add_argument("image", nargs="?", help="only this image")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(fn=cmd_images)
+
+    url_help = f"server URL (default $STACKBOX_URL or http://127.0.0.1:{DEFAULT_PORT})"
+    p = sub.add_parser(
+        "sandboxes", parents=[common], help="sandboxes the running server holds"
+    )
+    p.add_argument("--all", action="store_true", help="include ended sandboxes")
+    p.add_argument("--url", help=url_help)
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(fn=cmd_sandboxes)
+
+    p = sub.add_parser(
+        "placement",
+        parents=[common],
+        help="where a sandbox went, every attempt, and its cost",
+    )
+    p.add_argument("id", help="sandbox id")
+    p.add_argument("--url", help=url_help)
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(fn=cmd_placement)
+
+    p = sub.add_parser(
+        "usage", parents=[common], help="sandbox time and estimated cost per provider"
+    )
+    p.add_argument(
+        "--since", default="24h", help="ISO time or 30m, 24h, 7d (default 24h)"
+    )
+    p.add_argument("--url", help=url_help)
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(fn=cmd_usage)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        if (
+            getattr(args, "config", None)
+            or hasattr(args, "port")
+            or hasattr(args, "host")
+        ):
+            args.host = getattr(args, "host", "127.0.0.1")
+            args.port = getattr(args, "port", DEFAULT_PORT)
+            args.strategy = None
+            raise SystemExit(cmd_serve(args))
+        parser.print_help()
+        raise SystemExit(0)
+    raise SystemExit(args.fn(args))