How to Handle Sandboxer Rate Limits and Concurrency Caps

sbx limits --json | jq -c '{maxActiveSandboxes, activeSandboxes, activeStates, minute: .starts.minute.limit, startLimitsExempt: .currentLimits.startLimitsExempt, standardLimits}'

{"maxActiveSandboxes":100,"activeSandboxes":6,"activeStates":["provisioning","provisioned","cloning","ready","idle","running"],"minute":1073741824,"startLimitsExempt":true,"standardLimits":{"activeSandboxes":100,"creationRatePerMinute":12,"creationRequestsPerDay":200,"creationRequestsPerHour":60}}

# gate.py: start Sandboxer sandboxes under your plan's limits (Python 3.9+, stdlib only)
import json, os, random, threading, time, urllib.error, urllib.request
from collections import deque
from contextlib import contextmanager
from datetime import datetime, timezone

API = os.environ.get("SANDBOXER_API_URL", "https://sandboxer.com/api/v1")


class GiveUp(Exception):
    pass


def request(method, path, body=None, headers=None):
    h = {"Authorization": f"Bearer {os.environ['SANDBOXER_API_KEY']}", **(headers or {})}
    data = None
    if body is not None:
        h["Content-Type"] = "application/json"
        data = json.dumps(body).encode()
    req = urllib.request.Request(API + path, data=data, headers=h, method=method)
    try:
        with urllib.request.urlopen(req, timeout=90) as res:
            return res.status, res.headers, json.loads(res.read() or b"{}")
    except urllib.error.HTTPError as e:
        return e.code, e.headers, json.loads(e.read() or b"{}")


def classify(status, code):
    """What a start refusal means for the caller."""
    if status < 300:
        return "ok"
    if code in ("no_ready_machine", "capacity_exceeded"):
        return "next_size"   # nothing was created; try the next size now, back off after the last
    if code in ("rate_limited", "daily_limit_reached"):
        return "wait"        # a start window is full; it frees at Retry-After / resetsAt
    if code in ("limit_reached", "member_limit_reached"):
        return "queue"       # too many active; only a stop or delete frees a place
    if code in ("idempotency_in_progress", "card_check_pending") or status >= 500:
        return "retry"       # transient; same key, backoff
    return "fail"            # every other 4xx: the request has to change


def backoff(attempt, base=0.5, cap=30.0):
    return random.uniform(0, min(cap, base * 2 ** attempt))   # full jitter


class Gate:
    def __init__(self, max_slots=None, max_wait=900, window=60.0):
        _, _, lim = request("GET", "/limits")
        free = max(1, lim["maxActiveSandboxes"] - lim["activeSandboxes"])
        self.size = min(free, max_slots or free)
        self.slots = threading.BoundedSemaphore(self.size)
        self.per_window = min(lim["starts"]["minute"]["limit"], 10_000)
        self.window, self.max_wait = window, max_wait
        self.recent, self.lock = deque(), threading.Lock()

    def _pace(self):
        # Stay under the per-minute start limit instead of finding it with a 429.
        with self.lock:
            now = time.monotonic()
            while self.recent and now - self.recent[0] > self.window:
                self.recent.popleft()
            if len(self.recent) >= self.per_window:
                time.sleep(self.window - (now - self.recent[0]))
                self.recent.popleft()
            self.recent.append(time.monotonic())

    def start(self, job_id, sizes=("default", "small"), **extra):
        deadline, attempt = time.monotonic() + self.max_wait, 0
        while True:
            for size in sizes:
                self._pace()
                body = {"type": size, "name": job_id, "failFast": True, **extra}
                # One key per job and size: a retry of the same body replays, a new size is a new request.
                status, headers, data = request("POST", "/sandboxes", body, {"Idempotency-Key": f"{job_id}-{size}"})
                kind = classify(status, data.get("code"))
                if kind == "ok":
                    return data["sandbox"]["id"], size
                if kind != "next_size":
                    break
            if kind == "fail":
                raise GiveUp(f"{status} {data.get('code')}: {data.get('message')} ({data.get('requestId')})")
            details = (data.get("error") or {}).get("details") or {}
            delay = float(headers.get("Retry-After") or details.get("retryAfterSeconds") or 0)
            delay = delay or backoff(attempt, base=5.0 if kind == "queue" else 0.5)
            if time.monotonic() + delay > deadline:
                raise GiveUp(f"{status} {data.get('code')}: would wait {delay:.0f}s, past max_wait ({data.get('requestId')})")
            print(f"{job_id}: {status} {data.get('code')} -> {kind}, sleeping {delay:.1f}s", flush=True)
            time.sleep(delay)
            attempt += 1

    @contextmanager
    def sandbox(self, job_id, **kw):
        with self.slots:                      # held from create until the delete is accepted
            sid, size = self.start(job_id, **kw)
            try:
                yield sid, size
            finally:
                request("DELETE", f"/sandboxes/{sid}", headers={"X-Sandboxer-Confirm-Delete": sid})


def ts():
    return datetime.now(timezone.utc).strftime("%H:%M:%S")

import json, time, urllib.request
from concurrent.futures import ThreadPoolExecutor
from gate import Gate, GiveUp, request, ts

gate = Gate(max_wait=60, window=2.0)   # mock minute limit is 3; a 2 s window keeps the test short
print("slots", gate.size, "starts per window", gate.per_window)

def job(name):
    try:
        with gate.sandbox(name) as (sid, size):
            status, _, out = request("POST", f"/sandboxes/{sid}/commands", {"command": "echo ok", "timeoutSeconds": 60})
            return f"{ts()} {name}: {sid} {size} exit={out['exitCode']}"
    except GiveUp as e:
        return f"{ts()} {name}: gave up: {e}"

jobs = ["job1", "job2-no-default", "job3-rate", "job4-full", "job5-daily", "job6-badsize", "job7"]
t0 = time.time()
with ThreadPoolExecutor(max_workers=len(jobs)) as pool:
    for line in pool.map(job, jobs):
        print(line)
stats = json.load(urllib.request.urlopen("http://127.0.0.1:8765/_stats"))   # the mock's own counters
print("max sandboxes at once:", stats["maxConcurrent"])
print("creates:", [(round(t - t0, 1), j, s) for t, j, s in stats["creates"]])

slots 2 starts per window 3
10:42:26 job1: sb_mock1 default exit=0
10:42:26 job2-no-default: sb_mock2 small exit=0
job3-rate: 429 rate_limited -> wait, sleeping 2.0s
job4-full: 503 capacity_exceeded -> next_size, sleeping 0.3s
10:42:30 job3-rate: sb_mock4 default exit=0
10:42:30 job4-full: sb_mock3 default exit=0
10:42:30 job5-daily: gave up: 429 daily_limit_reached: would wait 30000s, past max_wait (req_mock)
10:42:32 job6-badsize: gave up: 400 invalid_type: type must be one of small, default, large, xlarge. (req_mock)
10:42:32 job7: sb_mock5 default exit=0
max sandboxes at once: 2
creates: [(-0.0, 'job1', 'default'), (-0.0, 'job2-no-default', 'small'), (4.0, 'job4-full', 'default'), (4.0, 'job3-rate', 'default'), (6.0, 'job7', 'default')]

from concurrent.futures import ThreadPoolExecutor
from gate import Gate, GiveUp, request, ts

gate = Gate(max_slots=1)            # at most one of these sandboxes at a time
print(ts(), "slots", gate.size, "starts per minute", gate.per_window)

def job(name):
    try:
        with gate.sandbox(name, ttlSeconds=900) as (sid, size):
            print(ts(), name, "started", sid, size, flush=True)
            _, _, out = request("POST", f"/sandboxes/{sid}/commands", {"command": "nproc; uptime -p", "timeoutSeconds": 60})
            print(ts(), name, "exit", out.get("exitCode"), repr(out.get("stdout")), flush=True)
        print(ts(), name, "deleted", sid, flush=True)
        return sid
    except GiveUp as e:
        print(ts(), name, "gave up:", e)

with ThreadPoolExecutor(max_workers=2) as pool:
    ids = list(pool.map(job, ["batch-1", "batch-2"]))
for sid in ids:
    status, _, data = request("GET", f"/sandboxes/{sid}")
    print(sid, status, data.get("code") or data.get("sandbox", {}).get("state"))

10:44:35 slots 1 starts per minute 10000
10:44:35 batch-1 started sb_u67mrj2lid default
10:44:36 batch-1 exit 0 '4\nup 0 minutes\n'
10:44:36 batch-1 deleted sb_u67mrj2lid
10:44:36 batch-2 started sb_uv2c5d66ze default
10:44:38 batch-2 exit 0 '4\nup 0 minutes\n'
10:44:38 batch-2 deleted sb_uv2c5d66ze
sb_u67mrj2lid 404 not_found
sb_uv2c5d66ze 404 not_found