Repository avatar
AI Tools
v0.1.0
active

sandboxrouting

com.sandboxrouting/sandboxrouting

One MCP server for 108 cloud sandbox providers: free tiers first, failover, jobs that move boxes.

Documentation

sandboxrouting

One router for every cloud sandbox provider. You ask for a sandbox; the router picks a provider that still has free usage left, fails over when one refuses, and keeps track of what each sandbox costs. The four ways providers expose themselves — an SDK, a REST API, a CLI and an MCP server — are each here once, for all of them.

import { createRouter } from "sandboxrouting";

const router = await createRouter();               // config file + keys from the environment
const sbx = await router.create({ timeoutSec: 600 });
const r = await sbx.commands.run("python3 -c 'print(6*7)'");
await sbx.files.write("/work/app.py", "print('hi')");
console.log(sbx.provider, r.stdout);               // e.g. "modal 42"
await sbx.kill();

Providers

108 providers are built in: 105 cloud providers plus your own hardware (openci, OpenSandbox, local Docker). One of them, runloop, is off by default. Terms were checked on 2026-11-11 or 2026-11-12 against each provider's pricing page, which its adapter links, and those that had changed, or were added since, on 2026-11-21 (each adapter's checked date says which). Terms change, so you can override any of them in config.

The 17 added on 2026-11-12 (tensorlake, buddy, boxd, maritime, promigence, zode, boxcompute, lizard, munito, nanite, render, quave, beam, mosaic, nodus, cathedral, dory) are written from each provider's published API and tested against local servers that speak it. None has been run against the real service yet. Nor has opensandbox (added 2026-11-14), written from OpenSandbox's OpenAPI specs and its JS SDK, nor the 59 added on 2026-11-21 (groundbox, briq, kubi, orble, runtime, digitalocean, docker-cloud, novita, smol, isorun, instavm, prized, zipbox, superserve, eqvps, solari, pilldrops, langsmith, miosa, cloudrun, gke-agent-sandbox, azure-sandboxes, agentbay, tencent, volcengine, railway, vers, oblien, runta, stateset, saas-sandbox, sandbox0, watasu, keln, mandala, platinum, inngest, archil, openpond, gmi, openreward, baseten, chalk, voidrun, kosa8, primeintellect, sandboxer, workpaper, rayrun, tama, tangle, nirvana, agental, cyqle, machine0, hyperbrowser, lightcone, offstage, islo), written the same way from each provider's docs, OpenAPI spec or official SDK and checked against its pages that day.

Some of those speak another provider's API or reach theirs indirectly. novita, tencent and volcengine speak E2B's API and share the e2b adapter's code; nirvana serves OpenSandbox's API and shares the opensandbox adapter's code. chalk, and primeintellect's commands, speak the Connect protocol's JSON form to services whose SDKs speak gRPC; tama and gke-agent-sandbox's commands speak gRPC-Web. openreward speaks a session API known only from its SDK, and machine0 has no REST API: its adapter calls the tools of machine0's MCP server over HTTP. The big clouds (cloudrun, gke-agent-sandbox, azure-sandboxes, agentbay, tencent, volcengine, railway) need some console setup first, described in docs/providers-iam.md.

Free every month

idFree usageFree limitsPaid afterIsolation
modal$30 / month100 concurrent, 24 h~$0.19/h (2 vCPU, 2 GiB)gVisor
northflank$20 / month2 sandboxes~$0.017/vCPU-hcontainer
freestyle200 vCPU-h + 400 GiB-h (≈ $13)10 concurrent$0.040/vCPU-hmicroVM
vercel5 CPU-h + 420 GB-h (≈ $9.5)10 concurrent, 45 min$0.128/vCPU-h (active CPU only) + $0.0212/GB-hFirecracker
instaboxone 4 vCPU / 8 GiB machine, always free11 machine, 8 h per run$0.004/vCPU-hFirecracker
upstash5 CPU-hours10 concurrent, 2 vCPU / 4 GB$0.05/vCPU-h (active CPU only), memory free: $0.10/h for 2 vCPU / 4 GB busycontainer
cloudflare375 vCPU-min + 25 GiB-h (≈ $0.68) with Workers Paid ($5/mo)—$0.072/vCPU-h (active CPU only) + $0.009/GiB-h; 2 vCPU comes with 8 GiB, ≈ $0.22/h busycontainer
tensorlakeone 1 vCPU / 1 GB sandbox, always free1 sandbox, 1 h (2 h once verified)$0.07/vCPU-h (active CPU only, 20% minimum) + $0.015/GB-hFirecracker
fly$5 / month shared with sprites (counted as $2.50 each2; card required)3 machines~$0.035/h (2 shared vCPU / 4 GB)Firecracker
sprites$5 / month shared with fly (counted as $2.50 each2; card required)3 Sprites$0.0385/vCPU-h (active CPU only) + $0.021875/GB-h; idle Sprites are freeFirecracker
solari$3 / month1 sandbox, 1 h$0.171/h (2 vCPU / 4 GB)Cloud Hypervisor
langsmith8 LSU / month ($8, ≈ 42 h)10 sandboxes$0.189/h (2 vCPU / 4 GiB)Firecracker3
miosa$1 / month5 sandboxes$0.0893/h (2 vCPU / 4 GB)Firecracker
cloudrun240k vCPU-s + 450k GiB-s (≈ $5.22; billing account)Preview; needs the execd image$0.158/h (2 vCPU / 4 GiB)gVisor4
azure-sandboxes180k vCPU-s + 360k GiB-s (≈ $5.40)42 vCPU / 4 GiB is tier L$0.216/h (2 vCPU / 4 GiB)microVM
archil1 vCPU-h + 2 GiB-h (≈ $0.095), no card5 concurrent, 30 min sessions, egress allowlist$0.055/vCPU-h + $0.020/GiB-hFirecracker
agental$5 / month (card required)2 small at once until the first top-up; tiny and small only$0.027/h (2 vCPU / 4 GiB)VM
cyqle60 min a day (counted as 30 h a month), no card51 desktop, 1 vCPU / 1 GB, 60-minute sessions$0.04/h pay as you go (2 vCPU / 4 GB), or $12/mo per desktopnot published6
isloincluded in a plan from $20/mo (counted as one Machine's month)5usage limits unpublished≈ $0.027/h (the $20 plan over a month)microVM

One-time credit

idFree usageFree limitsPaid afterIsolation
daytona$200710 vCPU total$0.050/vCPU-hcontainer
blaxelup to $200710 concurrent, 7 days$0.041/GB-h (memory only)microVM
e2b$10010 concurrent, 1 h$0.050/vCPU-hFirecracker
tenki (Luxor Agent Cloud, was Tenki)$100 when you first add a card5 concurrent$0.050/vCPU-hmicroVM
boxlite$100 when you add a card7per plan$0.050/vCPU-hmicroVM
dedalus$20 (beta access needed)—rates unpublished (estimate $0.05/vCPU-h)Cloud Hypervisor
createos~$5 (500 credits)71 sandbox, 1 vCPU / 1 GB$0.036/vCPU-hFirecracker
quivvo$5 (signup queue)1 machine$0.005/vCPU-h (shared)Firecracker
celesto$5, expires after 30 days1 sandbox$0.015/h (1 vCPU / 2 GB)Firecracker
agent37$5 (card required)3 awake$0.0011/vCPU-hgVisor
boat25 trial hours (≈ $0.45; card required)2 concurrent, 2 h$0.018/h (2 vCPU / 4 GB)VM
boxd€30 (counted as $32.97; card likely required)50 machines€0.039/vCPU-h (active CPU only) + €0.012/GiB-hKVM microVM
maritime$20 trial cap, 7 days (card required)24 h$0.022/h (2 vCPU / 4 GB)Firecracker
promigence$100 (card and expiry not stated)20 concurrent, 1 h$0.166/h (2 vCPU / 4 GiB)not published6
zode$10, no card2 running, 55 s per command$0.0175/h (2 vCPU / 4 GB)Cloud Hypervisor
boxcompute$5, expires after 14 days2 running$0.05/h (0.5 vCPU / 1 GiB)VM
lizard$5, 7-day trial (card required)1 Small running, 1 h$0.0162/h (2 vCPU / 4 GB)Firecracker
munito$0.90, 7-day trial (card required)2 concurrent, 2 h$0.018/h (2 vCPU / 4 GiB)microVM
buddy$5 for 14 days (card required)—$0.0144/vCPU-h + $0.0144/GB-hVM
groundbox$5 (no card; 3,000 CI min a month too)72 concurrent, 2 vCPU / 4 GB, 1 h until a card$0.04/vCPU-h, memory includedFirecracker
briq€10 (counted as $10.99; no card)5 at once, up to medium (2 vCPU / 4 GB)€0.03/h (2 shared vCPU / 4 GB); free asleepFirecracker
runtime$5 in a 7-day Pro trial (card required)100 vCPUs at once$0.03/vCPU-h (active CPU only) + $0.008/GB-h; $25/mo planFirecracker
docker-cloud$250 promotional credit (card required)10 concurrent, 24 h$0.07/vCPU-h, memory includedmicroVM
novita$100 after a short survey, no card5 concurrent, 1 h, 2 vCPU / 4 GiB$0.035/vCPU-h + $0.0115/GiB-hnot published6
smol$100, no card4 running, 4 vCPU each$0.05/vCPU-h (active CPU only) + $0.0162/GB-h used + a $0.04/h basemicroVM
isorun$50, no card—$0.025/vCPU-h + $0.015/GiB-hmicroVM
instavm$50 (card on file)5 active$0.050/vCPU-h + $0.016/GB-hmicroVM
prized$30, no card10 at once, 2 vCPU / 4 GB, 60 min of running$0.04/vCPU-h + $0.0125/GB-hFirecracker
zipbox$25 for a $5 top-up (counted as $20; card required)250 box names ever8$0.0137/h (2 vCPU / 4 GB)not published6
pilldrops$5 (no card)5 concurrent, 4 h, 2 vCPU / 2 GB$0.13/h (2 vCPU / 2 GB)container9
railway$5, expires after 30 days (no card)10 running, 2 vCPU / 2 GB, 5 idle minutes$0.069/vCPU-h (active CPU only) + $0.069/GB-hVM
vers$5 ($50 more with a card)7—$0.04/vCPU-h + $0.01/GiB-h; asleep, only disk is billedVM
runta$50, no card732 vCPU / 64 GiB across runtimes on the trial$0.0504/vCPU-h + $0.0162/GiB-hnot published6
stateset$25 trial (card required)Hobby: 10 at once, 45 min$0.0746/h (2 vCPU / 4 GB dedicated, billed at 50% of allocation)10gVisor
saas-sandbox (Sandbox as a Service)$5, no card20 at once, 24 h, 10 min per command$0.09/h (2 vCPU / 4 GB)VM
sandbox0$5 (card required)20 running$0.015/GiB-h (memory only; CPU follows memory)gVisor
voidrun₹4,600 (counted as $49.64; no card)7300 s per command; sleeps after 60 idle seconds₹3.71/vCPU-h (active CPU only) + ₹1.19/GB-h (≈ $0.040 + $0.0129)microVM
workpaperone free hour (counted as $0.01, no card)4 running; India only; no incoming ports$0.010/h (2 vCPU / 4 GB) on Pro ($15/mo, all credit); $0.033/h pay as you goVM
rayrun¥50 (≈ $7.04)11—$0.014/h (2 vCPU / 4 GiB, ¥0.10)11microVM
hyperbrowser$5 (5,000 credits), no card1 concurrent session$0.045/vCPU-h + $0.015/GiB-h ($0.15/h at 2 vCPU / 4 GiB)Firecracker
offstage$5, no card (prepaid: each create reserves its timeout)macOS only (os: "macos"), 24 h, 30 min per command$1.10/h per sandboxmacOS user account12

Paid only

idPriceNotesIsolation
koyeb$0.0144/h per vCPU, 1 GB each included ($0.0288/h for 2 vCPU / 2 GB)microVM
morph$0.05/vCPU-hfree credit disputed13VM (memory snapshots)
together$0.045/vCPU-hcustom plansFirecracker
depot$0.18/vCPU-h (CPU only)7-day trialmicroVM
namespace$0.09/h per vCPU + 2 GB3 h max; a 30-day trial (no card) isn't countedmicroVM
lambda-microvm$0.10/vCPU-h + $0.013/GB-hneeds the execd imageFirecracker (ARM64)
thunder$0.051/vCPU-haccess through sales; exec over SSHFirecracker (GPUs)
exedev$0.105/h (2 vCPU + 4 GiB) on top of a plan30 s per commandVM
nanite$0.072/vCPU-h (active CPU only) + $0.0432/GB-hfixed size; stops after 30 idle secondsmicroVM
render$0.12/vCPU-h (active CPU only) + $0.019/GB-hbeta; no public URLs yetFirecracker
quave$0.03125/h per zCloud (0.5 vCPU + 0.5 GB), as many as the larger of CPU or memory needs: $0.25/h for 2 vCPU / 4 GBenabled per account; size and image come from a templategVisor
beam$0.05/vCPU-h + $0.01/GiB-h$20/mo plan includes $20 of creditcontainer
mosaic$0.05/h per 2 vCPU / 4 GiBfree while hibernatedFirecracker
nodus$0.0357/h (2 vCPU / 4 GiB)prepaid; no outbound network unless askedgVisor-style
cathedral$0.01/h (2 vCPU / 4 GiB)prepaid; 24 h max; files under /work; asleep, only disk is billedconfidential VM, shared14
dory$0.0288/h (2 shared vCPU / 4 GB)prepaid; 10 min per commandVM
kubi$0.035/h (4 vCPU / 8 GB, the only size)private beta, accounts approved by hand; credit needs a $20/mo persistent screen firstVM
orble$0.015/h (2 vCPU / 4 GiB)prepaid; 10 min per command; free while suspendedVM
digitalocean$0.044/vCPU-h (active CPU only) + $0.0095/GB-hprepaid; 4 min per command; files only under /workspacemicroVM
superserve$0.166/h (2 vCPU / 4 GiB)a free trial of unpublished size, no cardFirecracker
eqvps$0.132/h (2 vCPU / 4 GB)prepaid in crypto; 20 at once, 24 h maxFirecracker
gke-agent-sandbox$0.109/h (2 vCPU / 4 GiB, Autopilot pod rate)your cluster with agent-sandbox, a warm pool and the sandbox-router4container (the warm pool's runtime)
agentbay$0.0992/h (2 vCPU / 4 GB)free Basic plan, but compute is billed; 50 s per commandnot published6
tencent$0.13/h (2 vCPU / 4 GiB, 0.94 CNY)11size set by a sandbox tool made in the consolemicroVM (Cube)
volcengine$0.062/h (2 vCPU / 4 GB, 0.44 CNY)11size set by an E2B-compatible template; only the creating process reaches a sandboxmicroVM
oblien$0.03/vCPU-h (active CPU only) + $0.008/GiB-hprepaid wallet; files move through exec (its file API is text-only)Firecracker
watasu€0.072/vCPU-h + €0.0144/GiB-h (≈ $0.22/h for 2 vCPU / 4 GiB)prepaid balance needed to start; size from the template on the free Basic plannot published6
keln$0.0504/vCPU-h + $0.0162/GiB-h ($0.166/h for 2 vCPU / 4 GiB)prepaid; 3 running until the first top-up, 24 h maxmicroVM
mandala$0.03/vCPU-h + $0.015/GB-h ($0.12/h for 2 vCPU / 4 GB), pay as you gowhole desktops; a plan or prepaid credits needed; ends 10 min at the earliestVM
platinum$0.0324/vCPU-h + $0.0108/GiB-h ($0.108/h for 2 vCPU / 4 GiB)prepaid; new orgs capped at 2 vCPU / 2 GiB a sandbox; no TTLCloud Hypervisor
inngest$0.0396/vCPU-h + $0.0108/GB-h ($0.1224/h for 2 vCPU / 4 GB)beta, Pro plan and up; 1 h of runtime a sandbox, 5 min per command; REST taken from the SDKmicroVM
openpond$0.072/vCPU-h + $0.0234/GiB-h + disk ($0.24/h for 2 vCPU / 4 GiB)free plan's monthly usage unpublished, not counted; one combined output streamnot published6
gmi$0.17/h (2 vCPU / 4 GiB; $0.0861 1 / 2, $0.34 4 / 8)early access; size and image set by a templatenot published6
openreward$0.0504/vCPU-h + $0.0162/GiB-h ($0.1656/h for 2 vCPU / 4 GiB)runs in an environment workspace made on openreward.ai; an idle session is reaped after about 15 mincontainer
baseten$0.0655/vCPU-h + $0.0211/GiB-h ($0.2154/h for 2 vCPU / 4 GiB)10 at once; idle sandboxes go on standby (storage only)not published6
chalk$0.0249/vCPU-h + $0.008/GiB-h preemptible ($0.082/h for 2 vCPU / 4 GiB)preemptible by default; runs on the K8S compute class15container15
kosa8$0.15/h (2 vCPU / 4 GB), counted by vCPUa plan first (from $29/mo with 100 sandbox-hours); hours past it in $15 packsmicroVM
primeintellect$0.02/vCPU-h + $0.0125/GiB-h ($0.09/h for 2 vCPU / 4 GiB; launch rates until 2026-12-22)prepaid; first use of an image converts it to a VM imagemicroVM
sandboxer$0.018/h (2 vCPU / 4 GB)a plan first (from $20/mo, its dollars come back as machine time); 600 s per commandCloud Hypervisor
tama$0.0454/h (2 vCPU / 4 GB)prepaid credit; GPU machines too; gRPC-Web APIVM
tangle$0.049/h (2 vCPU / 4 GB), never below $0.04/hprepaid credit; size set by the templatecontainer (Docker or Firecracker, its choice)
nirvana$0.048/h (2 vCPU / 4 GB)you pay for the sandbox cluster's nodes, idle or not; needs a cluster made firstcontainer (on per-customer VM nodes)
machine0$0.052/h (2 vCPU / 4 GB)prepaid; bills while stopped too, so pause suspends (image storage only); 5 min per command; MCP API onlyVM
lightcone$0.38/vCPU-h (active CPU only, 6.25% minimum) + $0.095/GiB-hcomputer-use desktops; screenshots and clicks aren't exposed through the routerVM

Your own hardware

idFree usageIsolation
openciunlimited, on your workersFirecracker / gVisor / Hyper-V
opensandboxunlimited, on your Docker host or Kubernetes clustercontainer (set isolation in config if your runtime is stronger)
dockerunlimited, on this machinecontainer

Off by default

runloop is built in but off: a RUNLOOP_API_KEY alone doesn't route there. Runloop is winding down. Its docs say transition support for existing customers ended 2026-11-13, and on 2026-11-21 api.runloop.ai no longer resolved and platform.runloop.ai answered 503. If your account still works, turn it on with "runloop": { "enabled": true }. Its terms when it was last checked: $50 of one-time credit, 3 running, 48 h each, then $0.108/vCPU-h, VM isolation.

Notes:

  • boxd, briq and Watasu bill in euros. Their prices and free credit are converted at one rate, 1.099 USD per euro (the ECB reference rate on 2026-11-20). VoidRun bills in rupees, converted at the ECB rates of that day (≈ 92.67 INR per USD). Both rates are kept in src/providers/currency.ts.
  • A vCPU rate marked "active CPU only" is billed only while the CPUs are busy; memory is billed for every second the box runs. smol also bills a $0.04/h wall-clock base, which rides on its memory rate ($0.01 per GiB-hour over the default 4 GiB). See Active-CPU billing for how the router ranks and meters them.
  • Groundbox's pricing page says its CI minutes reset each month but not that the $5 does, so the $5 is treated as one-time. Its free credit can be exhausted by CI minutes as well.
  • Superserve gives new accounts a free trial for their first sandbox without saying how much, so nothing is counted as free; set freeTier in config once you know your account's.
  • Tenki is now Luxor Agent Cloud (tenki.cloud redirects to luxor.ai). The id stays tenki; the adapter reads LUXOR_API_KEY / LUXOR_AUTH_TOKEN / LUXOR_API_ENDPOINT as the SDK does, and the old TENKI_* names still work.
  • Runta, Watasu and Archil run commands only over a WebSocket protocol their SDKs speak, so their adapters load the SDK for exec (@runta/runta-sdk, @watasu/sdk, disk; Archil's needs Node 22.19 or newer) and use REST for everything else. Install the one you use. Reaching a Watasu sandbox's data plane resets its deadline, so the adapter passes the time it has left and the router also deletes it at its deadline.
  • Vers's newer docs create computers through a v2 operation API whose exec and file routes aren't documented; the adapter uses the v1 API its generated SDKs speak, which has no TTL, so the router deletes a Vers VM at its deadline.
  • Inngest documents its sandboxes through its TypeScript SDK; the inngest adapter speaks the REST calls that SDK makes (read from inngest 4.26.2), which Inngest says may change during the beta. OpenPond likewise names openpond-sdk as the contract, and its adapter speaks that SDK's calls.
  • Mandala, Platinum, Archil, Inngest and OpenPond stop or pause a sandbox at its deadline instead of deleting it (Platinum has no deadline at all), so the router deletes those at the deadline.

Not built

ProviderWhy
AWS Nitro SandboxesIt has no sandbox API. It's an EC2 feature: Firecracker on a Nitro Enclaves parent instance, or ISOLATED_SANDBOX tasks in ECS/EKS. The ECS path (RunTask plus ECS Exec) could become an adapter, but AWS doesn't say whether ECS Exec works in sandboxed tasks.
OpenAI hosted containersChecked 2026-11-21. The Containers API creates, lists and deletes containers and moves files, but has no call that runs a command: commands run only when a model issues a shell or code-interpreter call through the Responses API.
CubeIt never had an API (Mac app, web and SSH only), and it is shutting down: new machines blocked since 2026-11-06, all machines deleted 2026-12-20.
JilebiChecked 2026-11-21. Machines are made in its web console and reached over SSH and routed subdomains; it publishes no API to create a machine or run a command (its blog lists "programmability" as future work). $0.009/vCPU-h + $0.009/GB-h.
CloudishChecked 2026-11-21. A container host for web apps: its API deploys an image as a project and starts replicas reached over HTTP through its proxy, with no call that runs a command or moves a file. A sandbox would need our own exec server deployed as a private project (as cloudrun does), but Cloudish doesn't restrict traffic between tenants' pods, and a replica loses everything when it idles out. $0.1007/h at 2 CPU / 4 GB, $0.10 credit with no card.
microsandbox cloudThe cloud is a private beta (access on request). Its REST API creates, starts, stops and deletes sandboxes but has no exec or file route: commands ride an undocumented "sandbox command channel" that only the SDK speaks, and the npm SDK is a native binding. Checked 2026-11-21.

Keys and access surfaces

idKey(s)How the adapter connects
e2bE2B_API_KEYSDK e2b
daytonaDAYTONA_API_KEYSDK @daytona/sdk
modalMODAL_TOKEN_ID, MODAL_TOKEN_SECRETSDK modal (gRPC)
vercelVERCEL_TOKEN, VERCEL_TEAM_ID, VERCEL_PROJECT_ID (or VERCEL_OIDC_TOKEN)SDK @vercel/sandbox
runloopRUNLOOP_API_KEYSDK @runloop/api-client
freestyleFREESTYLE_API_KEYSDK freestyle
blaxelBL_API_KEY, BL_WORKSPACESDK @blaxel/core
northflankNORTHFLANK_TOKEN, NORTHFLANK_PROJECTSDK @northflank/js-client
cloudflareCLOUDFLARE_SANDBOX_URL, CLOUDFLARE_SANDBOX_TOKENREST, to the bridge Worker in templates/cloudflare-worker
instaboxINSTABOX_API_KEYREST api.instabox.sh
upstashUPSTASH_BOX_API_KEYSDK @upstash/box
tenkiLUXOR_API_KEY or LUXOR_AUTH_TOKEN (the old TENKI_API_KEY / TENKI_AUTH_TOKEN still work)SDK @tenkicloud/sandbox (also published as @luxorai/sandbox)
boxliteBOXLITE_API_KEYSDK @boxlite-ai/boxlite (native: macOS arm64, Linux glibc)
dedalusDEDALUS_API_KEYREST dcs.dedaluslabs.ai/v1
createosCREATEOS_SANDBOX_API_KEYREST api.sb.createos.sh/v1
quivvoQUIVVO_API_KEYREST tryquivvo.com/api/v1
celestoCELESTO_API_KEYSDK @celestoai/sdk
agent37AGENT37_API_KEYREST api.agent37.com/v1 + sandbox.agent37.app
boatBOAT_API_KEYREST boat.dev/api/v1
tensorlakeTENSORLAKE_API_KEYREST api.tensorlake.ai + <id>.sandbox.tensorlake.ai
buddyBUDDY_TOKEN, BUDDY_WORKSPACE, BUDDY_PROJECT (BUDDY_REGION for EU/AS)REST api.buddy.works
boxdBOXD_API_KEYSDK @boxd-sh/sdk (gRPC; there is no REST API)
maritimeMARITIME_API_KEYREST api.maritime.sh + the sandbox's data plane
promigencePROMIGENCE_API_KEYREST api.promigence.ai/v1
zodeZODE_API_KEYREST api.zode.dev/v1
boxcomputeBOXCOMPUTE_API_KEYREST api.boxcompute.ai/api/v2
lizardLIZARD_API_KEY, LIZARD_PROJECT_IDREST lizard.build/api
munitoMUNITO_API_KEYREST api.munito.ai/sandboxes/v1
novitaNOVITA_API_KEY (NOVITA_DOMAIN for another region)SDK e2b, pointed at us-phx-1.sandbox.novita.ai
smolSMOL_CLOUD_TOKENREST api.smolmachines.com/v1
isorunISORUN_API_KEYREST run-.isorun.ai/v1 (region from the key)
instavmINSTAVM_API_KEYREST api.instavm.io
prizedPRIZED_API_KEYREST api.prized.dev/api/v1 + the sandbox's edge
zipboxZIPBOX_API_KEYREST api.tribes.xyz + the box's own API
koyebKOYEB_API_TOKENSDK @koyeb/sandbox-sdk
flyFLY_API_TOKEN, FLY_APPREST api.machines.dev/v1
spritesSPRITES_TOKENREST api.sprites.dev/v1 (the SDK needs Node 24)
morphMORPH_API_KEYSDK morphcloud
togetherTOGETHER_API_KEYSDK together-sandbox
depotDEPOT_TOKENSDK @depot/sandbox
namespaceNSC_TOKENSDK @namespacelabs/sdk
lambda-microvmLAMBDA_MICROVM_IMAGE + AWS credentialsSDK @aws-sdk/client-lambda-microvms, plus execd (templates/aws-lambda-microvm)
thunderTNR_API_TOKENREST api.thundercompute.com:8443/v1, plus system ssh
exedevEXE_API_TOKEN (minted with generate-api-key --cmds=new,ssh,rm,ls)REST POST exe.dev/exec
naniteNANITE_API_KEYREST api.nanite.run/v1
renderRENDER_API_KEY, RENDER_WORKSPACE_IDREST api.render.com/v1 + per-sandbox connect tokens
quaveQUAVEONE_USER_TOKEN, QUAVEONE_ACCOUNT_ID, QUAVEONE_APP_ID, QUAVEONE_SANDBOX_TEMPLATE_IDREST api.quave.cloud/api/public/v1
beamBEAM_TOKEN, BEAM_WORKSPACE_IDSDK @beamcloud/beam-js
mosaicMOSAIC_API_TOKENREST sandbox.mosaicos.com/v1
nodusNODUS_API_KEY, NODUS_PROJECTREST api.nodus-compute.ai/apis/nodus.dev/v1
cathedralCATHEDRAL_API_KEYREST cathedral.computer/v1
kelnKELN_API_KEYREST sandbox.keln.ai/v1 (commands stream as SSE)
mandalaMANDALA_API_KEYREST app.mandala.computer/api/v1
platinumPT_TOKEN (PT_API_URL for a self-hosted control plane)REST api.platinum.dev/v1
inngestINNGEST_SIGNING_KEY (INNGEST_ENV for a branch environment)REST api.inngest.com/v2/sandboxes, the calls the inngest SDK makes
archilARCHIL_API_KEY (ARCHIL_REGION, default aws-us-east-1)REST control.<region>.archil.com/api for the lifecycle; SDK disk (Node 22.19+) for commands
openpondOPENPOND_API_KEYREST api.openpond.ai/v1/sandboxes, the calls openpond-sdk makes
gmiGMI_SANDBOX_API_KEY, GMI_SANDBOX_TEMPLATE (an Agent template id or name)REST console.gmicloud.ai/api/v2 + the sandbox's data plane
doryDORY_API_KEYREST api.dory.run/v1 + data.dory.run
groundboxGROUNDBOX_API_KEYREST api.groundbox.dev/v1
briqBRIQ_API_KEYREST api.briq.cloud/v1
kubiKUBI_API_KEYREST api.trykubi.com/v1
orbleORBLE_API_KEYREST orble.tech/v1
runtimeRUNTIME_API_KEYREST api.withruntime.com/v2
digitaloceanDIGITALOCEAN_TOKENREST api.digitalocean.com/v2/harness-runtime
docker-cloudDOCKER_ID, DOCKER_PAT (with Cloud Sandboxes access)REST connect.docker.com/sandboxes/v1 + the sandbox's endpoint
superserveSUPERSERVE_API_KEYREST api.superserve.ai + sandbox.superserve.ai (per-sandbox access token)
eqvpsEQVPS_API_KEYREST api.eqvps.com/api/v1/eqvps
solariSOLARI_API_KEYREST api.getsolari.com (exec and signed file URLs; no WebSocket)
pilldropsPILLDROPS_API_KEYREST pilldrops.com/v1
versVERS_API_KEYREST api.vers.sh/api/v1
oblienOBLIEN_CLIENT_ID, OBLIEN_CLIENT_SECRETREST api.oblien.com/v1 + the vm.oblien.com runtime gateway (short-lived JWT)
runtaRUNTA_API_KEYREST api.runta.com/v2, exec through SDK @runta/runta-sdk (WebSocket)
statesetSTATESET_API_KEYREST api.sandbox.stateset.app/api/v1
saas-sandboxAAS_API_KEYREST sandbox-as-a-service.com/v1
sandbox0SANDBOX0_TOKENREST api.sandbox0.ai/api/v1
watasuWATASU_API_KEY (options.team for a shared team)REST api.watasu.io/v1, exec through SDK @watasu/sdk (WebSocket)
langsmithLANGSMITH_API_KEY (LANGSMITH_ENDPOINT for EU, LANGSMITH_WORKSPACE_ID for org keys)REST api.smith.langchain.com/api/v2/sandboxes + each sandbox's data plane
miosaMIOSA_API_KEYREST api.miosa.ai/api/v1
railwayRAILWAY_TOKEN (project token), or RAILWAY_API_TOKEN + RAILWAY_ENVIRONMENT_IDGraphQL backboard.railway.com/graphql/v2
agentbayAGENTBAY_API_KEY (AGENTBAY_REGION, AGENTBAY_IMAGE_ID optional)REST (OpenAPI RPC) agentbay.<region>.aliyuncs.com
tencentTENCENT_AGS_API_KEY, TENCENT_AGS_TOOL (TENCENT_AGS_REGION optional)SDK e2b, at <region>.tencentags.com
workpaperWORKPAPER_API_KEY (from workpaper keys create)REST api.workpaper.co/v1/computers
rayrunRAYRUN_TOKEN (console API token)REST api.rayrunos.com/v1
tamaTAMA_TOKENgRPC-Web gateway.tama.computer (api.v1.ApiService), hand-encoded protobuf
tangleTANGLE_API_KEYREST sandbox.tangle.tools/e2b (its plain-HTTP routes)
nirvanaNIRVANA_API_KEY (sandbox edit permission), NIRVANA_SANDBOX_CLUSTER_ID (a ready cluster)REST api.nirvanalabs.io/v1/sandboxes (OpenSandbox) + execd through the cluster's gateway
agentalAGENTAL_API_KEYREST agental.io/v1
volcengineVOLCENGINE_E2B_API_KEY, VOLCENGINE_E2B_TEMPLATE_ID (VOLCENGINE_E2B_REGION optional)SDK e2b, at api.vefaas-e2b.sandbox-<region>.volcapig.com
openrewardOPENREWARD_API_KEY, OPENREWARD_ENVIRONMENT (an environment you made, user/env)session API at sessions.openreward.ai (server-sent events), as the openreward SDK speaks it
basetenBASETEN_API_KEY (BASETEN_TEAM_ID optional)REST api.baseten.co/v1/sandboxes with a 2 h sandbox token from /v1/token, + each sandbox's runtime API
chalkCHALK_CLIENT_ID, CHALK_CLIENT_SECRET (CHALK_ENVIRONMENT, CHALK_API_SERVER optional)Connect (JSON) chalk.sandbox.v2 services at api.chalk.ai, token from /v1/oauth/token
voidrunVOIDRUN_API_KEYREST api.void-run.com/api
kosa8KOSA8_API_KEYREST api.kosa8.com/v1
primeintellectPRIME_API_KEY (with the sandbox scope; PRIME_TEAM_ID optional)REST api.primeintellect.ai/api/v1/sandbox + the sandbox gateway (Connect stream for commands)
sandboxerSANDBOXER_API_KEYREST sandboxer.com/api/v1
cyqleCYQLE_API_KEY (options.slotId for a paid desktop)REST api.cyqle.in/v1, then the desktop's region (api-us / api-eu)
isloISLO_API_KEYREST api.islo.dev/auth/token (key for a session token) + ca.compute.islo.dev
hyperbrowserHYPERBROWSER_API_KEYREST api.hyperbrowser.ai/api + each sandbox's runtime URL and token
offstageOFFSTAGE_API_KEYREST api.offstage.cloud/v1
machine0MACHINE0_API_KEY (MACHINE0_SSH_KEY_ID optional)MCP app.machine0.io/mcp (JSON-RPC tools/call over HTTP)
lightconeTZAFON_API_KEYREST api.tzafon.ai
openciOPENCI_URL, OPENCI_TOKENREST /v1/sandboxes
opensandboxOPEN_SANDBOX_DOMAIN, optional OPEN_SANDBOX_API_KEYREST /v1/sandboxes + execd in the sandbox
cloudrunGOOGLE_CLOUD_PROJECT, CLOUD_RUN_REGION, CLOUD_RUN_SANDBOX_IMAGE + GOOGLE_OAUTH_ACCESS_TOKEN or GOOGLE_APPLICATION_CREDENTIALS(_JSON)REST run.googleapis.com/v2 (instances), plus execd (templates/cloud-run-sandbox)
gke-agent-sandboxAGENT_SANDBOX_K8S_API, AGENT_SANDBOX_ROUTER_URL, AGENT_SANDBOX_WARM_POOL + AGENT_SANDBOX_K8S_TOKEN or Google credentialsKubernetes API (SandboxClaim) + sandbox-router (gRPC-Web, REST)
azure-sandboxesAZURE_SUBSCRIPTION_ID, AZURE_RESOURCE_GROUP, AZURE_SANDBOX_GROUP, AZURE_REGION + AZURE_ACCESS_TOKEN or AZURE_TENANT_ID/AZURE_CLIENT_ID/AZURE_CLIENT_SECRETREST management.{region}.azuredevcompute.io
dockernone (SBR_DOCKER=0 turns it off)docker CLI

Provider SDKs are optional peer dependencies, loaded only when that provider is used: npm install sandboxrouting e2b modal installs the router plus two providers. A provider whose key is set but whose SDK is missing is skipped with an install hint.

How a provider is chosen

A routing strategy makes the choice, and you can switch it. The hard rules come first and are the same under every strategy, so no strategy can route around them. sbr route prints the ranked plan and why each provider sits where it does. sbr route --compare prints the plan under every strategy. The full design is in docs/routing.md.

StrategyOrder
free-first (default)Lanes: monthly free usage (the most at risk before its reset goes first), one-time credit (the largest share left goes first), your own hardware, then paid (cheapest first).
cheapestAny free usage by price, then your hardware, then paid by price.
balancedThe free-first lanes. Within a free lane, a weighted score of free value, health, speed, free headroom and load (weights in config). In the paid lane, price comes first.
fastestUnbilled first, then paid. Within each, the shortest expected time to a ready box: median create latency ÷ success rate. A provider never tried gets one try. The one strategy that pays more for speed.
spreadThe free-first lanes. Within a free lane, the most free slots first (lowest live/cap, fewest recent creates), so fan-out doesn't trip one provider's rate limit. In the paid lane, price comes first.

You pick a strategy three ways:

  • in config, with "routing": { "strategy": "balanced" };
  • per request, with strategy: "fastest" (--strategy);
  • by registering your own with router.registerStrategy({ name, description, rank }).

Within a lane, priority in config breaks ties first. The lanes keep paid usage off by default: with allowPaid: false nothing is ever billed, and a request no free tier can take fails with the reason for every provider. You can turn paid usage on globally or per provider. With maxPaidUsdPerMonth set, paid routing stops when the month's spend reaches it. Your own hardware (openci, OpenSandbox, local Docker) goes after the free lanes. With selfHosted: "first" it goes ahead of them, and with "never" it's removed.

A provider is left out when:

  • it has no key, or it is disabled;

  • it lacks a capability in needs (ports, pause, customImage, gpu, snapshot, extendTimeout, fileList);

  • it can't run the requested image;

  • the timeout is over its maximum;

  • execTimeoutSec is over its per-command cap (exe.dev cuts commands off at 30 s);

  • its isolation is weaker than minIsolation (container < gvisor < microvm/vm);

  • it runs another operating system than the request's os (linux unless the request says macos; offstage is the macOS provider);

  • its circuit is open (see below);

  • neither free nor paid usage can take the request. Free fails when:

    • the tier is used up;
    • what's left won't cover the whole request;
    • its concurrency is full;
    • the timeout is over the free lifetime cap.

    Paid fails when it isn't allowed, or when the month's budget won't cover the whole request.

Live sandboxes reserve what they can still spend: until their deadline, at their own size. So a free tier takes a request only if, after those reservations, it covers the full timeout at the size the provider will create. A paid request needs the same from the budget. Extending a sandbox (sbr extend) or resuming one reserves the time it adds under the same rule, or is refused. With allowPaid: false, no sandbox can run past its free tier, and maxPaidUsdPerMonth is a hard cap.

The router re-checks the provider under the ledger lock when reserving. A request planned as free that loses the last free slot or credit to a parallel request moves on to the next provider. It never quietly becomes paid.

If the chosen provider refuses, the router tries the next one, and the refusal changes what it does next:

RefusalWhat happens next
402 or "out of credit"The free tier is marked used up until the monthly reset. Other grants are checked again after 1 day, then 2, then 4, then weekly while they keep refusing. When a mark lapses, one request checks whether the tier is back while the others skip it; a free create that works clears the mark.
429The provider is cooled down for a minute, even when the body says "quota": that is nearly always a cap on how many run at once. Only a 429 that says money ran out ("credit", "billing", "insufficient balance") counts as used-up credit.
401 or 403The provider is skipped for 10 minutes.
Network errors and 5xxThe router moves on to the next provider. Three in a row open the provider's circuit: it is skipped for 2 minutes. The cooldown doubles with each further failure, up to 30. Then one request probes it.

sandbox.route records every provider tried or skipped and why. sbr providers shows each provider's health: the success rate of recent creates and the circuit state. This health is computed from the last 50 outcomes whenever it is read, and sbr reset <provider> clears it.

Metering

No provider has an API that reports remaining free credit, which the research for this router confirmed. So the router meters locally. Every sandbox's running time is recorded as billing segments. Pausing closes a segment. A sandbox past its deadline is billed only up to the deadline. Cost is running time × (vCPU × vCPU price + GiB × GiB price), using the provider's prices or yours.

Usage outside the router (the provider's console, another tool) isn't seen. For a one-time credit you have already spent part of, set usedBeforeUsd. If a provider refuses for quota anyway, the mark above catches it.

Some providers bill the vCPUs only while they are busy (pricing.billing: "active-cpu": Vercel, Cloudflare, Render, Upstash Box, Fly Sprites, boxd, SuperHQ Nanite, Tensorlake, Runtime, DigitalOcean Harness Runtime, Railway, smol). Strategies rank these by the expected cost, with the vCPUs busy activeCpuShare of the time (default 0.3; set routing.activeCpuShare for your workload, or providers.<id>.pricing.activeCpuShare for one provider), so cheapest compares them fairly. Reservations and metering still count every vCPU busy, since the router can't see CPU time: a busy box can't overrun a free tier or a budget, and the router stops using such a free tier a little before the provider would. Details in docs/routing.md.

Jobs: work that moves between boxes

A sandbox can die, its provider can refuse, or a free tier's limits can end it: a lifetime cap (E2B's free hour, Vercel's 45 minutes), running out of credit, the provider failing. A job keeps going through all of that. It is ordered steps plus a working directory. The workdir is checkpointed after each step, so the job continues on another box from where it stopped.

const job = await router.jobs.run({
  sandbox: { image: "python:3.12-slim" },          // routed like router.create
  files: { "main.py": "print('hi')" },             // the initial workdir ($HOME/work)
  setup: [{ run: "pip install -q requests" }],     // runs again on every new box
  steps: [
    { run: "python main.py > out.txt" },
    { run: "curl -fsS -X POST https://hooks.example/done", idempotent: false },
  ],
});
console.log(job.state, job.migrations, job.placements.map((p) => `${p.provider}:${p.endReason}`));
  • Planned moves. Before each step the job checks the box. If the box can't fit the next step, the job extends it when the provider allows that within the free lifetime cap; otherwise it moves. It also moves when the free credit won't cover the step and another provider ranks first, when a quota or auth refusal or an open circuit hits the box's provider, and, with rebalance, off a paid box when a free one is available.
  • Unplanned losses. If a box vanishes, its provider refuses, or errors repeat, the job moves to a new box and restores the last checkpoint. The step that was running runs again, but only if it is idempotent (the default). Steps with outside effects are marked idempotent: false, so the job fails rather than run them twice. A non-zero exit is the step's own failure unless it has retries. Exit 137 can move the job to a box with twice the memory (growMemoryOnOom).
  • Crashes. The process driving a job holds a lease. If it dies, the job reads as orphaned after 60 s, and sbr job resume <id> (or sbr serve, every 5 minutes) continues it from what the ledger recorded.
  • Waiting. When no provider can take the job now, it waits only if a reason lapses within maxWaitSec: a rate-limit mark, a circuit, or a full free tier whose next sandbox ends soon. Otherwise it fails at once with every provider's reason.

Checkpoints live in ~/.sandboxrouting/checkpoints/ and are checked by SHA-256. When the job ends, the last one is the result: sbr job download <id> saves it. router.move(id) does the same move once for an interactive sandbox: it copies the workdir to a new box, then kills the old one. The design and every decision table are in docs/routing.md.

The four surfaces

All four share one ledger (~/.sandboxrouting/ledger.json; SBR_HOME moves it). It is locked for every update and written whole, so the CLI, the REST server and an MCP server running at once agree on what is live and what is spent.

SDK: create, connect(id), list, kill, status, plan, sweep, move(id), strategies(), registerStrategy(s), and jobs (run, submit, resume, get, list, cancel, workspace, sweep). A sandbox has:

  • commands.run(cmd, {cwd, env, timeoutSec, onStdout, onStderr})
  • files.read, files.readBytes, files.write, files.list
  • getUrl(port), setTimeout(sec), pause(), resume(), kill()

connect("e2b:abc123") adopts a sandbox created outside the router.

CLI: sbr --help.

sbr providers                 # free-tier status, health and circuit of every provider
sbr check                     # live create/exec/files/kill on every configured free provider
sbr route --needs ports       # where a sandbox would go, and why the others were skipped
sbr route --compare           # the same request under every strategy
sbr strategies                # the strategies, and which one is active
sbr run -- python3 -c 'print(42)'          # create, run, kill; exit code passes through
id=$(sbr create --image node:22 --timeout 900 --strategy fastest)
sbr exec "$id" -- npm test
sbr move "$id"                # copy its workdir to a new box, kill the old one
sbr kill "$id"
sbr job run --step "make" --step "make test"   # steps that survive losing a box
sbr job status <job-id>       # where it ran, why it moved, how each step ended
sbr job download <job-id>     # the final workdir, as a .tgz

REST API: sbr serve --port 8787. Set serverToken in config (or SBR_SERVER_TOKEN) to require Authorization: Bearer …. The endpoints are listed at the top of src/server/http.ts: POST /v1/sandboxes, POST /v1/sandboxes/{id}/exec, GET|PUT /v1/sandboxes/{id}/files?path=, GET /v1/providers, POST /v1/route[?compare=1], GET /v1/strategies, POST /v1/sandboxes/{id}/move, and the jobs: POST /v1/jobs (202 with the job's id; ?wait=1 to wait for the end), GET /v1/jobs[/{id}], POST /v1/jobs/{id}/resume|cancel, GET /v1/jobs/{id}/workspace. Every 5 minutes the server reconciles with the providers, reaps boxes left behind by finished jobs, and resumes orphaned jobs. POST /v1/sweep does it on demand and returns { sandboxes, jobs }.

MCP server: sbr mcp (stdio). Its tools are list_providers, list_strategies, create_sandbox, run_command, read_file, write_file, list_files, get_url, set_timeout, move_sandbox, list_sandboxes, kill_sandbox, and for jobs run_job, job_status, list_jobs, resume_job and cancel_job. run_job waits up to waitSec, then returns the job's id to poll with job_status. For Claude Code:

claude mcp add sandboxes -- npx -y sandboxrouting mcp

Other clients take the same command (npx -y sandboxrouting mcp) in their MCP config, with your provider keys in its env. From a clone, node /path/to/sandboxrouting/dist/cli.js mcp runs the local build instead. The server is listed in the MCP Registry as com.sandboxrouting/sandboxrouting.

AgentRun

sandboxrouting/agentrun is a computer provider for AgentRun: one provider that gives an AgentRun server every sandboxrouting provider able to boot AgentRun's box image, routed free usage first, with failover. It implements AgentRun's MachineHost with the router in-process, as a dial host (the machine's agentrun-dial connects to the AgentRun server), and reports the provider it chose in the computer's labels. AgentRun keeps durable runs, cost caps and the run timeline. Tested against fake providers only, not yet against AgentRun's conformance suite or a live provider. See docs/agentrun.md.

import { create } from "sandboxrouting/agentrun"; // needs @parcha/agentrun-computer too
const provider = create({ strategy: "free-first", providers: "daytona,modal,fly", dial });

Configuration

./sandboxrouting.json, else ~/.sandboxrouting/config.json, or the path in SBR_CONFIG. Every field is optional. See sandboxrouting.example.json:

{
  "routing": { "strategy": "free-first" },   // cheapest | balanced | fastest | spread | yours
  "allowPaid": false,              // SBR_ALLOW_PAID=1 for one run
  "maxPaidUsdPerMonth": 10,
  "selfHosted": "after-free",      // "first" | "after-free" | "never"
  "defaults": { "timeoutSec": 300 },
  "providers": {
    "e2b": { "usedBeforeUsd": 12.5 },
    "daytona": { "freeTier": { "kind": "monthly-credit", "usd": 200 }, "priority": 10 },
    "modal": { "options": { "ports": [8080] } },
    "docker": { "isolation": "gvisor" },     // when Docker runs with runtime runsc
    "fly": { "enabled": false }
  },
  "jobs": { "maxMigrations": 5, "maxWaitSec": 300, "rebalance": false }
}

routing also takes weights for balanced, circuitBreaker settings, and activeCpuShare, the expected busy share of the vCPUs used to rank providers that bill only active CPU (default 0.3). A provider's pricing override takes vcpuSecondUsd, gibSecondUsd, sandboxSecondUsd, billing ("wall" or "active-cpu") and activeCpuShare. jobs takes the checkpoint mode, limits and timeouts. Both are documented in docs/routing.md. policy still works as the old name for routing.strategy.

sbr reset <provider> clears a provider's quota, rate-limit and auth marks, and its health history, after you top up or fix a key.

Usage dashboard

A router can report what its ledger records to a dashboard that shows how your workloads spread across providers: sandbox count, sandbox-hours and memory GiB-hours per day and provider, spend against the free usage each provider has left, refusals and failed creates, health and the circuit breaker, live sandboxes with their state as of now, and jobs with every move and why. It is two packages in this repository, both MIT: back/ (an ingest and read API on Postgres) and dashboard/ (Next.js). Reporting is off unless you turn it on.

Self-hosting

cp deploy/.env.example deploy/.env          # set POSTGRES_PASSWORD and SBR_ADMIN_TOKEN
docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d --build

That runs Postgres, back on port 8787 and the dashboard on port 3000. Sign in with SBR_ADMIN_TOKEN, then make an ingest key for each router under API keys (or set SBR_INGEST_TOKEN too). Each image is configured only by environment variables:

back
DATABASE_URLpostgres://… (required). Migrations run at startup and only move forward.
SBR_ADMIN_TOKEN, SBR_INGEST_TOKENOptional keys for the first account, made if missing and never brought back once revoked. At least 24 characters.
SBR_SWEEP_TOKENLets a cron call POST /v1/sweep for every account.
PORTDefault 8787.
dashboard
BACK_URLback as the dashboard's server reaches it (required).
BACK_PUBLIC_URLback as routers reach it, for the setup snippet.
PORTDefault 3000.

Nothing has to run in the background: whatever changes with time (a sandbox past its deadline, a mark that lapsed, a job whose runner stopped) is worked out when the dashboard reads it, with the database's clock. The sweep only rolls up closed days so reads stay cheap; run it from any cron (curl -X POST -H "authorization: Bearer $SBR_SWEEP_TOKEN" http://back:8787/v1/sweep) or with the compose file's sweep profile. Without Docker, cd back && npm run build && DATABASE_URL=… node dist/main.js and cd dashboard && npm run build && BACK_URL=… npm start; node back/dist/cli.js account create <name> makes an account and prints its admin key.

Turning on the reporter

export SBR_REPORT_URL=http://localhost:8787
export SBR_REPORT_TOKEN=sbrk_…                # an ingest key

or in config:

{ "report": { "url": "https://back.example", "token": "sbrk_…", "metadataKeys": ["team"] } }

SBR_REPORT=0 turns it off for one run. createRouter (and so the CLI, REST server and MCP server) reports when it is on; for a router you construct yourself, wrap its ledger with reportingLedger. Only ids, provider ids, sizes, times, states and prices leave the machine, plus the metadata keys you list. Never commands, env, file contents, provider error messages or keys.

After every ledger write, and when a router starts, the reporter compares the ledger with what it last queued and queues an event for each thing that changed, in an outbox at $SBR_HOME/report/outbox.json (written whole, under a lock, like the ledger). Each event keeps its id until back acknowledges it, and back keeps the newest state of each sandbox, job and mark whatever order events arrive in, so a resend never counts twice. Routing never waits on back: a send times out after 4 s, and a failure backs off (recorded in the outbox, so other processes don't each retry a back end that is down) until the next router to start, or the same long-running one, delivers what is queued. Several quick changes may reach back as one state; the billing segments in it are complete.

Adding a provider

A provider is one file. Only create, exec and kill are required. The router implements file read, write and listing on top of exec (base64 in chunks, so binary is safe), and an adapter that can do better adds the native calls.

// src/providers/acme.ts
import { defineProvider, httpJson } from "./util.js";

export const acmeProvider = defineProvider({
  info: {
    id: "acme",
    name: "Acme Sandboxes",
    homepage: "https://acme.dev",
    env: ["ACME_API_KEY"],
    capabilities: ["customImage"],
    freeTier: {
      tier: { kind: "monthly-credit", usd: 10 },
      concurrency: 5,
      source: "https://acme.dev/pricing",
      checked: "2026-11-11",
    },
    pricing: { vcpuSecondUsd: 0.00001, gibSecondUsd: 0.000003, defaultCpu: 1, defaultMemoryMiB: 1024 },
  },
  async create(spec, ctx) {
    const s = await httpJson<{ id: string }>("https://api.acme.dev/v1/sandboxes", {
      headers: { authorization: `Bearer ${ctx.env.ACME_API_KEY}` },
      body: { image: spec.image, timeout: spec.timeoutSec, env: spec.env, metadata: spec.metadata },
    });
    return { providerSandboxId: s.id };
  },
  async exec(id, command, opts, ctx) { /* … */ return { stdout: "", stderr: "", exitCode: 0 }; },
  async kill(id, ctx) { /* … */ },
});

Then add it to src/providers/index.ts, or call router.register(acmeProvider) from your own code. To finish:

  • Add listAlive so sbr sweep can close sandboxes that died behind the router's back.
  • If the provider keeps a sandbox alive past the requested timeout, set enforcesTimeout: false in info. The router then deletes it at the deadline.
  • Make create throw errors with an HTTP status, so quota (402) and rate limits (429) fail over correctly. If the provider uses a status that means something else (a spent allowance as 429 or 409, a plan limit as 403), declare it with refusals() in src/providers/util.ts.
  • If the provider bills the vCPUs only while they are busy, set billing: "active-cpu" in pricing (and activeCpuFloor if it bills a minimum share), so strategies rank it by its expected cost.
  • Run the tests: test/providers.test.ts checks that every built-in declares its free-tier source and backs each capability it claims.

Providers with extra setup

  • Cloudflare has no hosted sandbox API: a sandbox is a Durable Object plus the Container it starts, inside your own Worker. Deploy the bridge in templates/cloudflare-worker (npm install, then npx wrangler secret put SANDBOX_TOKEN and npx wrangler deploy). Then set CLOUDFLARE_SANDBOX_URL to the Worker's URL and CLOUDFLARE_SANDBOX_TOKEN to the same secret. The bridge uses @cloudflare/sandbox 1.x and destroys each container at its deadline with a Durable Object alarm. The sandbox size is the instance_type in wrangler.jsonc.

  • No timeout of their own. These providers don't stop a sandbox at the requested timeout:

    • Fly Sprites, Celesto, BoxLite, Dedalus, CreateOS, exe.dev and Agent37 have no TTL.
    • A Northflank service restarts its container when it exits.

    Their adapters declare enforcesTimeout: false, so the router deletes the sandbox at the deadline itself. sbr sweep (run every 5 minutes by sbr serve) deletes any it missed.

  • AWS Lambda MicroVMs have no exec API. Build the image in templates/aws-lambda-microvm: its dependency-free execd.mjs runs commands and moves files behind the VM's endpoint. Then set LAMBDA_MICROVM_IMAGE to the image ARN.

  • Google Cloud Run sandboxes have no API of their own. Build the image in templates/cloud-run-sandbox and set CLOUD_RUN_SANDBOX_IMAGE; the region must offer Cloud Run instances (not us-central1, us-east1 or europe-west1).

  • GKE Agent Sandbox needs agent-sandbox installed with its extensions, a SandboxWarmPool whose pods run sandboxd, and the sandbox-router exposed outside the cluster. A cluster CA that Node doesn't trust goes in NODE_EXTRA_CA_CERTS.

  • Azure Container Apps Sandboxes need a sandbox group (Microsoft.App/sandboxGroups). The default image is the public ubuntu disk image; options.image names another public one, and a template (--template azure-sandboxes=<disk image id>) uses your own.

  • Thunder Compute runs commands over SSH only. The adapter generates a throwaway key, gets a certificate from the API, and uses the system ssh and ssh-keygen. Sandbox access is enabled through Thunder's sales team.

  • exe.dev has one API endpoint, POST /exec, which takes SSH command text and cuts each call off at 30 seconds. Mint a token that may run new, ssh, rm and ls.

  • Access gates: Dedalus Machines needs beta access (403 until admitted), and Quivvo puts new free accounts in a queue.

  • Together and Morph boot from snapshots. When you give an image (or nothing), the adapter builds the snapshot once per image or size and reuses it. A template (--template together=<alias>) skips that step.

  • Fly Machines needs an app you own (FLY_APP).

  • Northflank needs a project (NORTHFLANK_PROJECT).

  • Nirvana Labs runs sandboxes on a sandbox cluster you create first (dashboard, or POST /v1/sandbox_clusters with an instance type, node count and region). Its nodes are billed by the hour from then on, sandboxes or not. Set NIRVANA_SANDBOX_CLUSTER_ID once its status is ready.

  • Workpaper, Rayrun and tama keep a stopped or idle machine instead of deleting it (Workpaper pauses after an idle hour, Rayrun cold-stops at max_lifetime_seconds, tama stops at its idle ttl), so they declare enforcesTimeout: false too. A new Rayrun sandbox has no network by default: the adapter opens egress, and options.egress: "closed" keeps it shut. Its default image is ubuntu@1 (options.agent or a template names another).

Checking providers live

Each cloud adapter is type-checked against that provider's real SDK. The HTTP-only adapters (cloudflare, sprites) are tested against servers that speak their wire formats. A live run still needs your keys: set them, then run

sbr check                      # every configured provider that has free usage left
sbr check --provider koyeb     # a paid-only provider runs only when you name it

Each provider gets one small sandbox: it runs a command, writes, reads back and lists a file, then kills the sandbox. The check prints ok or the provider's own error.

Development

npm install
npm run lint         # ESLint over the whole repository (each check runs through hushrun)
npm run typecheck    # adapters are checked against the real provider SDK types
npm test             # the Docker ones run real containers when Docker is up
npm run simulate     # compare the routing strategies on a simulated month
npm run build && node dist/cli.js providers

back/ and dashboard/ are npm workspaces with their own checks: npm run lint|typecheck|test|build -w back (or -w dashboard). back's tests run on PGlite, a real Postgres in WebAssembly; TEST_DATABASE_URL=postgres://… runs them on a Postgres server instead, each test in its own database. cd back && DATABASE_URL=pglite:memory npm run dev starts back with nothing to set up.

CI runs lint, typecheck and the tests through hushrun, which skips what this exact code already passed: a test file that passed on the exact files it read doesn't run again. See CONTRIBUTING.md to send a change, and SECURITY.md to report a vulnerability.

Providers' names and terms

sandboxrouting isn't affiliated with or endorsed by any provider it supports. Their names are trademarks of their owners. Free tiers and prices are as each adapter's source page said on its checked date, and they change: check a provider's own terms before you rely on them, and override them in config (providers.<id>.freeTier, pricing) when yours differ.

License

MIT

The sandboxrouting name and logo are not covered by the MIT license.

Footnotes

  1. InstaBox's free plan is never billed, but it says its "early allowance" can end. It's modelled as a month of hours for one machine. ↩

  2. Fly's Free plan has one $5 a month for Machines and Sprites together, and the router meters each provider apart, so each counts $2.50: with both on, the two can't spend more than the $5. If you use only one, give it all: "fly": { "freeTier": { "kind": "monthly-credit", "usd": 5 } }. ↩ ↩2

  3. LangSmith documents Firecracker for its self-hosted sandboxes; its cloud pages say only "isolated". An LSU is $1; 8 LSU at 0.0576 LSU/vCPU-h + 0.01845 LSU/GiB-h is about 42 hours. ↩

  4. Cloud Run sandboxes start only from inside a Cloud Run container, so each router sandbox is one Cloud Run instance (Preview) running templates/cloud-run-sandbox, which runs commands in a sandbox with sandbox exec. Cloud Run claims gVisor, the weaker of its two generations. Azure says Container Apps Sandboxes bill like the Consumption plan but lists no sandbox meter, so its Consumption rates and free grant are used; Azure deletes a sandbox a day after it stops, paused ones included. gke-agent-sandbox runs in your own cluster: it's priced at GKE Autopilot's pod rate. On a cluster whose nodes you already pay for, set "gke-agent-sandbox": { "pricing": { "vcpuSecondUsd": 0, "gibSecondUsd": 0 } }. ↩ ↩2 ↩3

  5. Cyqle and Islo sell plans. Cyqle's free plan gives one desktop 60 minutes a day; a paid desktop ($6 to $45 a month) has unlimited session time, so model it as usage included in the plan: "cyqle": { "freeTier": { "tier": { "kind": "monthly-hours", "hours": 744 }, "concurrency": 1 }, "options": { "slotId": "<slot>", "plan": "standard" } }. Islo has no hourly rate: Machines are unlimited on every plan within usage limits it doesn't publish, so a plan is counted as one Machine's month of hours, and the paid rate is the $20 Engineer plan spread over that month. ↩ ↩2

  6. Promigence, Novita, Zipbox, AgentBay, Runta, Watasu, OpenPond, GMI Agentbox, Baseten and Cyqle don't say how their sandboxes are isolated, so a request with minIsolation skips them. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10

  7. The provider doesn't say whether the credit recurs, so it's treated as one-time, the safe reading. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8

  8. Zipbox names are permanent and an account may ever create 250, so its adapter reuses a pool of names (options.pool, default 32). Its docs don't pair tiers with sizes; xs to l are taken to be Tiny to Large. ↩

  9. PillDrops' pricing page says each sandbox is a dedicated microVM, but its llms.txt says "a microVM (or container)", so the adapter claims container, the weaker. ↩

  10. StateSet bills dedicated compute ($0.128/vCPU-h + $0.0106/GB-h on Hobby and Pro) at 50% of what is allocated, its estimate of average use, so the router counts half those rates. The Hobby plan's monthly allowance (5 vCPU-hours, 420 GB-hours) isn't counted as free usage. ↩

  11. Tencent, Volcengine and Rayrun bill in yuan; their prices are converted at 7.1 CNY per USD, kept in src/providers/currency.ts. ↩ ↩2 ↩3 ↩4

  12. offstage cloud runs each sandbox as a macOS user account on a shared Mac Studio, wiped when it closes; other accounts' processes and localhost servers are visible, so the adapter claims container, the weakest level. It's the only macOS provider: only requests with os: "macos" go to it, and no other request does. ↩

  13. Morph's own pages disagree (a 300 MCU starting credit vs none). If your account has it, set "morph": { "freeTier": { "kind": "one-time-credit", "usd": 15 } }. ↩

  14. Cathedral's rooms share one AMD SEV-SNP VM and are kept apart by a container runtime it doesn't name, so the adapter claims container, the weakest. ↩

  15. Chalk's SDK runs a command on its default host compute class only over a bidirectional stream, which fetch can't open, and on the K8S class through one unary call, so the adapter creates K8S-class sandboxes; one docs page says those don't support exec, which only a live run will settle. Chalk documents gVisor for its sandboxes but not for that class, so the adapter claims container. Non-preemptible work costs $0.0747/vCPU-h + $0.024/GiB-h. ↩ ↩2

NPM
sandboxrouting
Install Command
npm install sandboxrouting