Skip to content
Back to search

sandboxrouting

One router for 48 cloud sandbox providers (E2B, Daytona, Modal, Vercel, Cloudflare...). Uses every free tier first. SDK, REST API, CLI and MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jccorzo--sandboxrouting/badge.svg)](/listings/jccorzo--sandboxrouting)

HTML

<a href="/listings/jccorzo--sandboxrouting"><img src="/api/listings/jccorzo--sandboxrouting/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 877 lines
  1. # sandboxrouting
  2. One router for every cloud sandbox provider. You ask for a sandbox; the router picks a
  3. provider that still has free usage left, fails over when one refuses, and keeps track of
  4. what each sandbox costs. The four ways providers expose themselves — an SDK, a REST API, a
  5. CLI and an MCP server — are each here once, for all of them.
  6. ```ts
  7. import { createRouter } from "sandboxrouting";
  8. const router = await createRouter(); // config file + keys from the environment
  9. const sbx = await router.create({ timeoutSec: 600 });
  10. const r = await sbx.commands.run("python3 -c 'print(6*7)'");
  11. await sbx.files.write("/work/app.py", "print('hi')");
  12. console.log(sbx.provider, r.stdout); // e.g. "modal 42"
  13. await sbx.kill();
  14. ```
  15. ## Providers
  16. 108 providers are built in: 105 cloud providers plus your own hardware (openci, OpenSandbox,
  17. local Docker). One of them, `runloop`, is [off by default](#off-by-default). Terms were checked
  18. on 2026-11-11 or 2026-11-12 against each provider's pricing page, which its adapter links, and
  19. those that had changed, or were added since, on 2026-11-21 (each adapter's `checked` date says
  20. which). Terms change, so you can override any of them in config.
  21. The 17 added on 2026-11-12 (`tensorlake`, `buddy`, `boxd`, `maritime`, `promigence`, `zode`,
  22. `boxcompute`, `lizard`, `munito`, `nanite`, `render`, `quave`, `beam`, `mosaic`, `nodus`,
  23. `cathedral`, `dory`) are written from each provider's published API and tested against local
  24. servers that speak it. None has been run against the real service yet. Nor has `opensandbox`
  25. (added 2026-11-14), written from OpenSandbox's OpenAPI specs and its JS SDK, nor the 59 added on
  26. 2026-11-21 (`groundbox`, `briq`, `kubi`, `orble`, `runtime`, `digitalocean`, `docker-cloud`,
  27. `novita`, `smol`, `isorun`, `instavm`, `prized`, `zipbox`, `superserve`, `eqvps`, `solari`,
  28. `pilldrops`, `langsmith`, `miosa`, `cloudrun`, `gke-agent-sandbox`, `azure-sandboxes`,
  29. `agentbay`, `tencent`, `volcengine`, `railway`, `vers`, `oblien`, `runta`, `stateset`,
  30. `saas-sandbox`, `sandbox0`, `watasu`, `keln`, `mandala`, `platinum`, `inngest`, `archil`,
  31. `openpond`, `gmi`, `openreward`, `baseten`, `chalk`, `voidrun`, `kosa8`, `primeintellect`,
  32. `sandboxer`, `workpaper`, `rayrun`, `tama`, `tangle`, `nirvana`, `agental`, `cyqle`, `machine0`,
  33. `hyperbrowser`, `lightcone`, `offstage`, `islo`), written the same way from each provider's
  34. docs, OpenAPI spec or official SDK and checked against its pages that day.
  35. Some of those speak another provider's API or reach theirs indirectly. `novita`, `tencent` and
  36. `volcengine` speak E2B's API and share the `e2b` adapter's code; `nirvana` serves OpenSandbox's
  37. API and shares the `opensandbox` adapter's code. `chalk`, and `primeintellect`'s commands, speak
  38. the Connect protocol's JSON form to services whose SDKs speak gRPC; `tama` and
  39. `gke-agent-sandbox`'s commands speak gRPC-Web. `openreward` speaks a session API known only from
  40. its SDK, and `machine0` has no REST API: its adapter calls the tools of machine0's MCP server
  41. over HTTP. The big clouds (`cloudrun`, `gke-agent-sandbox`, `azure-sandboxes`, `agentbay`,
  42. `tencent`, `volcengine`, `railway`) need some console setup first, described in
  43. [docs/providers-iam.md](docs/providers-iam.md).
  44. ### Free every month
  45. | id | Free usage | Free limits | Paid after | Isolation |
  46. |---|---|---|---|---|
  47. | `modal` | $30 / month | 100 concurrent, 24 h | ~$0.19/h (2 vCPU, 2 GiB) | gVisor |
  48. | `northflank` | $20 / month | 2 sandboxes | ~$0.017/vCPU-h | container |
  49. | `freestyle` | 200 vCPU-h + 400 GiB-h (≈ $13) | 10 concurrent | $0.040/vCPU-h | microVM |
  50. | `vercel` | 5 CPU-h + 420 GB-h (≈ $9.5) | 10 concurrent, 45 min | $0.128/vCPU-h (active CPU only) + $0.0212/GB-h | Firecracker |
  51. | `instabox` | one 4 vCPU / 8 GiB machine, always free[^1] | 1 machine, 8 h per run | $0.004/vCPU-h | Firecracker |
  52. | `upstash` | 5 CPU-hours | 10 concurrent, 2 vCPU / 4 GB | $0.05/vCPU-h (active CPU only), memory free: $0.10/h for 2 vCPU / 4 GB busy | container |
  53. | `cloudflare` | 375 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 busy | container |
  54. | `tensorlake` | one 1 vCPU / 1 GB sandbox, always free | 1 sandbox, 1 h (2 h once verified) | $0.07/vCPU-h (active CPU only, 20% minimum) + $0.015/GB-h | Firecracker |
  55. | `fly` | $5 / month shared with `sprites` (counted as $2.50 each[^2]; card required) | 3 machines | ~$0.035/h (2 shared vCPU / 4 GB) | Firecracker |
  56. | `sprites` | $5 / month shared with `fly` (counted as $2.50 each[^2]; card required) | 3 Sprites | $0.0385/vCPU-h (active CPU only) + $0.021875/GB-h; idle Sprites are free | Firecracker |
  57. | `solari` | $3 / month | 1 sandbox, 1 h | $0.171/h (2 vCPU / 4 GB) | Cloud Hypervisor |
  58. | `langsmith` | 8 LSU / month ($8, ≈ 42 h) | 10 sandboxes | $0.189/h (2 vCPU / 4 GiB) | Firecracker[^3] |
  59. | `miosa` | $1 / month | 5 sandboxes | $0.0893/h (2 vCPU / 4 GB) | Firecracker |
  60. | `cloudrun` | 240k vCPU-s + 450k GiB-s (≈ $5.22; billing account) | Preview; needs the execd image | $0.158/h (2 vCPU / 4 GiB) | gVisor[^4] |
  61. | `azure-sandboxes` | 180k vCPU-s + 360k GiB-s (≈ $5.40)[^4] | 2 vCPU / 4 GiB is tier L | $0.216/h (2 vCPU / 4 GiB) | microVM |
  62. | `archil` | 1 vCPU-h + 2 GiB-h (≈ $0.095), no card | 5 concurrent, 30 min sessions, egress allowlist | $0.055/vCPU-h + $0.020/GiB-h | Firecracker |
  63. | `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 |
  64. | `cyqle` | 60 min a day (counted as 30 h a month), no card[^5] | 1 desktop, 1 vCPU / 1 GB, 60-minute sessions | $0.04/h pay as you go (2 vCPU / 4 GB), or $12/mo per desktop | not published[^6] |
  65. | `islo` | included in a plan from $20/mo (counted as one Machine's month)[^5] | usage limits unpublished | ≈ $0.027/h (the $20 plan over a month) | microVM |
  66. ### One-time credit
  67. | id | Free usage | Free limits | Paid after | Isolation |
  68. |---|---|---|---|---|
  69. | `daytona` | $200[^7] | 10 vCPU total | $0.050/vCPU-h | container |
  70. | `blaxel` | up to $200[^7] | 10 concurrent, 7 days | $0.041/GB-h (memory only) | microVM |
  71. | `e2b` | $100 | 10 concurrent, 1 h | $0.050/vCPU-h | Firecracker |
  72. | `tenki` (Luxor Agent Cloud, was Tenki) | $100 when you first add a card | 5 concurrent | $0.050/vCPU-h | microVM |
  73. | `boxlite` | $100 when you add a card[^7] | per plan | $0.050/vCPU-h | microVM |
  74. | `dedalus` | $20 (beta access needed) | — | rates unpublished (estimate $0.05/vCPU-h) | Cloud Hypervisor |
  75. | `createos` | ~$5 (500 credits)[^7] | 1 sandbox, 1 vCPU / 1 GB | $0.036/vCPU-h | Firecracker |
  76. | `quivvo` | $5 (signup queue) | 1 machine | $0.005/vCPU-h (shared) | Firecracker |
  77. | `celesto` | $5, expires after 30 days | 1 sandbox | $0.015/h (1 vCPU / 2 GB) | Firecracker |
  78. | `agent37` | $5 (card required) | 3 awake | $0.0011/vCPU-h | gVisor |
  79. | `boat` | 25 trial hours (≈ $0.45; card required) | 2 concurrent, 2 h | $0.018/h (2 vCPU / 4 GB) | VM |
  80. | `boxd` | €30 (counted as $32.97; card likely required) | 50 machines | €0.039/vCPU-h (active CPU only) + €0.012/GiB-h | KVM microVM |
  81. | `maritime` | $20 trial cap, 7 days (card required) | 24 h | $0.022/h (2 vCPU / 4 GB) | Firecracker |
  82. | `promigence` | $100 (card and expiry not stated) | 20 concurrent, 1 h | $0.166/h (2 vCPU / 4 GiB) | not published[^6] |
  83. | `zode` | $10, no card | 2 running, 55 s per command | $0.0175/h (2 vCPU / 4 GB) | Cloud Hypervisor |
  84. | `boxcompute` | $5, expires after 14 days | 2 running | $0.05/h (0.5 vCPU / 1 GiB) | VM |
  85. | `lizard` | $5, 7-day trial (card required) | 1 Small running, 1 h | $0.0162/h (2 vCPU / 4 GB) | Firecracker |
  86. | `munito` | $0.90, 7-day trial (card required) | 2 concurrent, 2 h | $0.018/h (2 vCPU / 4 GiB) | microVM |
  87. | `buddy` | $5 for 14 days (card required) | — | $0.0144/vCPU-h + $0.0144/GB-h | VM |
  88. | `groundbox` | $5 (no card; 3,000 CI min a month too)[^7] | 2 concurrent, 2 vCPU / 4 GB, 1 h until a card | $0.04/vCPU-h, memory included | Firecracker |
  89. | `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 asleep | Firecracker |
  90. | `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 plan | Firecracker |
  91. | `docker-cloud` | $250 promotional credit (card required) | 10 concurrent, 24 h | $0.07/vCPU-h, memory included | microVM |
  92. | `novita` | $100 after a short survey, no card | 5 concurrent, 1 h, 2 vCPU / 4 GiB | $0.035/vCPU-h + $0.0115/GiB-h | not published[^6] |
  93. | `smol` | $100, no card | 4 running, 4 vCPU each | $0.05/vCPU-h (active CPU only) + $0.0162/GB-h used + a $0.04/h base | microVM |
  94. | `isorun` | $50, no card | — | $0.025/vCPU-h + $0.015/GiB-h | microVM |
  95. | `instavm` | $50 (card on file) | 5 active | $0.050/vCPU-h + $0.016/GB-h | microVM |
  96. | `prized` | $30, no card | 10 at once, 2 vCPU / 4 GB, 60 min of running | $0.04/vCPU-h + $0.0125/GB-h | Firecracker |
  97. | `zipbox` | $25 for a $5 top-up (counted as $20; card required) | 250 box names ever[^8] | $0.0137/h (2 vCPU / 4 GB) | not published[^6] |
  98. | `pilldrops` | $5 (no card) | 5 concurrent, 4 h, 2 vCPU / 2 GB | $0.13/h (2 vCPU / 2 GB) | container[^9] |
  99. | `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-h | VM |
  100. | `vers` | $5 ($50 more with a card)[^7] | — | $0.04/vCPU-h + $0.01/GiB-h; asleep, only disk is billed | VM |
  101. | `runta` | $50, no card[^7] | 32 vCPU / 64 GiB across runtimes on the trial | $0.0504/vCPU-h + $0.0162/GiB-h | not published[^6] |
  102. | `stateset` | $25 trial (card required) | Hobby: 10 at once, 45 min | $0.0746/h (2 vCPU / 4 GB dedicated, billed at 50% of allocation)[^10] | gVisor |
  103. | `saas-sandbox` (Sandbox as a Service) | $5, no card | 20 at once, 24 h, 10 min per command | $0.09/h (2 vCPU / 4 GB) | VM |
  104. | `sandbox0` | $5 (card required) | 20 running | $0.015/GiB-h (memory only; CPU follows memory) | gVisor |
  105. | `voidrun` | ₹4,600 (counted as $49.64; no card)[^7] | 300 s per command; sleeps after 60 idle seconds | ₹3.71/vCPU-h (active CPU only) + ₹1.19/GB-h (≈ $0.040 + $0.0129) | microVM |
  106. | `workpaper` | one 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 go | VM |
  107. | `rayrun` | ¥50 (≈ $7.04)[^11] | — | $0.014/h (2 vCPU / 4 GiB, ¥0.10)[^11] | microVM |
  108. | `hyperbrowser` | $5 (5,000 credits), no card | 1 concurrent session | $0.045/vCPU-h + $0.015/GiB-h ($0.15/h at 2 vCPU / 4 GiB) | Firecracker |
  109. | `offstage` | $5, no card (prepaid: each create reserves its timeout) | macOS only (`os: "macos"`), 24 h, 30 min per command | $1.10/h per sandbox | macOS user account[^12] |
  110. ### Paid only
  111. | id | Price | Notes | Isolation |
  112. |---|---|---|---|
  113. | `koyeb` | $0.0144/h per vCPU, 1 GB each included ($0.0288/h for 2 vCPU / 2 GB) | | microVM |
  114. | `morph` | $0.05/vCPU-h | free credit disputed[^13] | VM (memory snapshots) |
  115. | `together` | $0.045/vCPU-h | custom plans | Firecracker |
  116. | `depot` | $0.18/vCPU-h (CPU only) | 7-day trial | microVM |
  117. | `namespace` | $0.09/h per vCPU + 2 GB | 3 h max; a 30-day trial (no card) isn't counted | microVM |
  118. | `lambda-microvm` | $0.10/vCPU-h + $0.013/GB-h | needs the execd image | Firecracker (ARM64) |
  119. | `thunder` | $0.051/vCPU-h | access through sales; exec over SSH | Firecracker (GPUs) |
  120. | `exedev` | $0.105/h (2 vCPU + 4 GiB) on top of a plan | 30 s per command | VM |
  121. | `nanite` | $0.072/vCPU-h (active CPU only) + $0.0432/GB-h | fixed size; stops after 30 idle seconds | microVM |
  122. | `render` | $0.12/vCPU-h (active CPU only) + $0.019/GB-h | beta; no public URLs yet | Firecracker |
  123. | `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 GB | enabled per account; size and image come from a template | gVisor |
  124. | `beam` | $0.05/vCPU-h + $0.01/GiB-h | $20/mo plan includes $20 of credit | container |
  125. | `mosaic` | $0.05/h per 2 vCPU / 4 GiB | free while hibernated | Firecracker |
  126. | `nodus` | $0.0357/h (2 vCPU / 4 GiB) | prepaid; no outbound network unless asked | gVisor-style |
  127. | `cathedral` | $0.01/h (2 vCPU / 4 GiB) | prepaid; 24 h max; files under /work; asleep, only disk is billed | confidential VM, shared[^14] |
  128. | `dory` | $0.0288/h (2 shared vCPU / 4 GB) | prepaid; 10 min per command | VM |
  129. | `kubi` | $0.035/h (4 vCPU / 8 GB, the only size) | private beta, accounts approved by hand; credit needs a $20/mo persistent screen first | VM |
  130. | `orble` | $0.015/h (2 vCPU / 4 GiB) | prepaid; 10 min per command; free while suspended | VM |
  131. | `digitalocean` | $0.044/vCPU-h (active CPU only) + $0.0095/GB-h | prepaid; 4 min per command; files only under /workspace | microVM |
  132. | `superserve` | $0.166/h (2 vCPU / 4 GiB) | a free trial of unpublished size, no card | Firecracker |
  133. | `eqvps` | $0.132/h (2 vCPU / 4 GB) | prepaid in crypto; 20 at once, 24 h max | Firecracker |
  134. | `gke-agent-sandbox` | $0.109/h (2 vCPU / 4 GiB, Autopilot pod rate) | your cluster with agent-sandbox, a warm pool and the sandbox-router[^4] | container (the warm pool's runtime) |
  135. | `agentbay` | $0.0992/h (2 vCPU / 4 GB) | free Basic plan, but compute is billed; 50 s per command | not published[^6] |
  136. | `tencent` | $0.13/h (2 vCPU / 4 GiB, 0.94 CNY)[^11] | size set by a sandbox tool made in the console | microVM (Cube) |
  137. | `volcengine` | $0.062/h (2 vCPU / 4 GB, 0.44 CNY)[^11] | size set by an E2B-compatible template; only the creating process reaches a sandbox | microVM |
  138. | `oblien` | $0.03/vCPU-h (active CPU only) + $0.008/GiB-h | prepaid wallet; files move through exec (its file API is text-only) | Firecracker |
  139. | `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 plan | not published[^6] |
  140. | `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 max | microVM |
  141. | `mandala` | $0.03/vCPU-h + $0.015/GB-h ($0.12/h for 2 vCPU / 4 GB), pay as you go | whole desktops; a plan or prepaid credits needed; ends 10 min at the earliest | VM |
  142. | `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 TTL | Cloud Hypervisor |
  143. | `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 SDK | microVM |
  144. | `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 stream | not published[^6] |
  145. | `gmi` | $0.17/h (2 vCPU / 4 GiB; $0.0861 1 / 2, $0.34 4 / 8) | early access; size and image set by a template | not published[^6] |
  146. | `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 min | container |
  147. | `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 published[^6] |
  148. | `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 class[^15] | container[^15] |
  149. | `kosa8` | $0.15/h (2 vCPU / 4 GB), counted by vCPU | a plan first (from $29/mo with 100 sandbox-hours); hours past it in $15 packs | microVM |
  150. | `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 image | microVM |
  151. | `sandboxer` | $0.018/h (2 vCPU / 4 GB) | a plan first (from $20/mo, its dollars come back as machine time); 600 s per command | Cloud Hypervisor |
  152. | `tama` | $0.0454/h (2 vCPU / 4 GB) | prepaid credit; GPU machines too; gRPC-Web API | VM |
  153. | `tangle` | $0.049/h (2 vCPU / 4 GB), never below $0.04/h | prepaid credit; size set by the template | container (Docker or Firecracker, its choice) |
  154. | `nirvana` | $0.048/h (2 vCPU / 4 GB) | you pay for the sandbox cluster's nodes, idle or not; needs a cluster made first | container (on per-customer VM nodes) |
  155. | `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 only | VM |
  156. | `lightcone` | $0.38/vCPU-h (active CPU only, 6.25% minimum) + $0.095/GiB-h | computer-use desktops; screenshots and clicks aren't exposed through the router | VM |
  157. ### Your own hardware
  158. | id | Free usage | Isolation |
  159. |---|---|---|
  160. | `openci` | unlimited, on your workers | Firecracker / gVisor / Hyper-V |
  161. | `opensandbox` | unlimited, on your Docker host or Kubernetes cluster | container (set `isolation` in config if your runtime is stronger) |
  162. | `docker` | unlimited, on this machine | container |
  163. ### Off by default
  164. `runloop` is built in but off: a `RUNLOOP_API_KEY` alone doesn't route there. Runloop is
  165. winding down. Its docs say transition support for existing customers ended 2026-11-13, and on
  166. 2026-11-21 `api.runloop.ai` no longer resolved and platform.runloop.ai answered 503. If your
  167. account still works, turn it on with `"runloop": { "enabled": true }`. Its terms when it was
  168. last checked: $50 of one-time credit, 3 running, 48 h each, then $0.108/vCPU-h, VM isolation.
  169. [^1]: InstaBox's free plan is never billed, but it says its "early allowance" can end. It's
  170. modelled as a month of hours for one machine.
  171. [^2]: Fly's Free plan has one $5 a month for Machines and Sprites together, and the router
  172. meters each provider apart, so each counts $2.50: with both on, the two can't spend more
  173. than the $5. If you use only one, give it all: `"fly": { "freeTier": { "kind":
  174. "monthly-credit", "usd": 5 } }`.
  175. [^3]: LangSmith documents Firecracker for its self-hosted sandboxes; its cloud pages say only
  176. "isolated". An LSU is $1; 8 LSU at 0.0576 LSU/vCPU-h + 0.01845 LSU/GiB-h is about 42 hours.
  177. [^4]: Cloud Run sandboxes start only from inside a Cloud Run container, so each router sandbox
  178. is one Cloud Run instance (Preview) running
  179. [templates/cloud-run-sandbox](templates/cloud-run-sandbox), which runs commands in a sandbox
  180. with `sandbox exec`. Cloud Run claims gVisor, the weaker of its two generations. Azure says
  181. Container Apps Sandboxes bill like the Consumption plan but lists no sandbox meter, so its
  182. Consumption rates and free grant are used; Azure deletes a sandbox a day after it stops,
  183. paused ones included. `gke-agent-sandbox` runs in your own cluster: it's priced at GKE
  184. Autopilot's pod rate. On a cluster whose nodes you already pay for, set
  185. `"gke-agent-sandbox": { "pricing": { "vcpuSecondUsd": 0, "gibSecondUsd": 0 } }`.
  186. [^5]: Cyqle and Islo sell plans. Cyqle's free plan gives one desktop 60 minutes a day; a paid
  187. desktop ($6 to $45 a month) has unlimited session time, so model it as usage included in the
  188. plan: `"cyqle": { "freeTier": { "tier": { "kind": "monthly-hours", "hours": 744 },
  189. "concurrency": 1 }, "options": { "slotId": "<slot>", "plan": "standard" } }`. Islo has no
  190. hourly rate: Machines are unlimited on every plan within usage limits it doesn't publish, so
  191. a plan is counted as one Machine's month of hours, and the paid rate is the $20 Engineer
  192. plan spread over that month.
  193. [^6]: Promigence, Novita, Zipbox, AgentBay, Runta, Watasu, OpenPond, GMI Agentbox, Baseten and
  194. Cyqle don't say how their sandboxes are isolated, so a request with `minIsolation` skips
  195. them.
  196. [^7]: The provider doesn't say whether the credit recurs, so it's treated as one-time, the safe
  197. reading.
  198. [^8]: Zipbox names are permanent and an account may ever create 250, so its adapter reuses a
  199. pool of names (`options.pool`, default 32). Its docs don't pair tiers with sizes; `xs` to
  200. `l` are taken to be Tiny to Large.
  201. [^9]: PillDrops' pricing page says each sandbox is a dedicated microVM, but its llms.txt says "a
  202. microVM (or container)", so the adapter claims `container`, the weaker.
  203. [^10]: StateSet bills dedicated compute ($0.128/vCPU-h + $0.0106/GB-h on Hobby and Pro) at 50%
  204. of what is allocated, its estimate of average use, so the router counts half those rates.
  205. The Hobby plan's monthly allowance (5 vCPU-hours, 420 GB-hours) isn't counted as free usage.
  206. [^11]: Tencent, Volcengine and Rayrun bill in yuan; their prices are converted at 7.1 CNY per
  207. USD, kept in `src/providers/currency.ts`.
  208. [^12]: offstage cloud runs each sandbox as a macOS user account on a shared Mac Studio, wiped
  209. when it closes; other accounts' processes and localhost servers are visible, so the adapter
  210. claims `container`, the weakest level. It's the only macOS provider: only requests with `os:
  211. "macos"` go to it, and no other request does.
  212. [^13]: Morph's own pages disagree (a 300 MCU starting credit vs none). If your account has it,
  213. set `"morph": { "freeTier": { "kind": "one-time-credit", "usd": 15 } }`.
  214. [^14]: Cathedral's rooms share one AMD SEV-SNP VM and are kept apart by a container runtime it
  215. doesn't name, so the adapter claims `container`, the weakest.
  216. [^15]: Chalk's SDK runs a command on its default host compute class only over a bidirectional
  217. stream, which fetch can't open, and on the K8S class through one unary call, so the adapter
  218. creates K8S-class sandboxes; one docs page says those don't support exec, which only a live
  219. run will settle. Chalk documents gVisor for its sandboxes but not for that class, so the
  220. adapter claims `container`. Non-preemptible work costs $0.0747/vCPU-h + $0.024/GiB-h.
  221. Notes:
  222. - boxd, briq and Watasu bill in euros. Their prices and free credit are converted at one rate,
  223. 1.099 USD per euro (the ECB reference rate on 2026-11-20). VoidRun bills in rupees, converted
  224. at the ECB rates of that day (≈ 92.67 INR per USD). Both rates are kept in
  225. `src/providers/currency.ts`.
  226. - A vCPU rate marked "active CPU only" is billed only while the CPUs are busy; memory is billed
  227. for every second the box runs. smol also bills a $0.04/h wall-clock base, which rides on its
  228. memory rate ($0.01 per GiB-hour over the default 4 GiB). See [Active-CPU
  229. billing](docs/routing.md#active-cpu-billing) for how the router ranks and meters them.
  230. - Groundbox's pricing page says its CI minutes reset each month but not that the $5 does, so the
  231. $5 is treated as one-time. Its free credit can be exhausted by CI minutes as well.
  232. - Superserve gives new accounts a free trial for their first sandbox without saying how much, so
  233. nothing is counted as free; set `freeTier` in config once you know your account's.
  234. - Tenki is now Luxor Agent Cloud (tenki.cloud redirects to luxor.ai). The id stays `tenki`; the
  235. adapter reads `LUXOR_API_KEY` / `LUXOR_AUTH_TOKEN` / `LUXOR_API_ENDPOINT` as the SDK does, and
  236. the old `TENKI_*` names still work.
  237. - Runta, Watasu and Archil run commands only over a WebSocket protocol their SDKs speak, so
  238. their adapters load the SDK for `exec` (`@runta/runta-sdk`, `@watasu/sdk`, `disk`; Archil's
  239. needs Node 22.19 or newer) and use REST for everything else. Install the one you use. Reaching
  240. a Watasu sandbox's data plane resets its deadline, so the adapter passes the time it has left
  241. and the router also deletes it at its deadline.
  242. - Vers's newer docs create computers through a v2 operation API whose exec and file routes
  243. aren't documented; the adapter uses the v1 API its generated SDKs speak, which has no TTL, so
  244. the router deletes a Vers VM at its deadline.
  245. - Inngest documents its sandboxes through its TypeScript SDK; the `inngest` adapter speaks the
  246. REST calls that SDK makes (read from `inngest` 4.26.2), which Inngest says may change during
  247. the beta. OpenPond likewise names `openpond-sdk` as the contract, and its adapter speaks that
  248. SDK's calls.
  249. - Mandala, Platinum, Archil, Inngest and OpenPond stop or pause a sandbox at its deadline
  250. instead of deleting it (Platinum has no deadline at all), so the router deletes those at the
  251. deadline.
  252. ### Not built
  253. | Provider | Why |
  254. |---|---|
  255. | AWS Nitro Sandboxes | It 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. |
  256. | OpenAI hosted containers | Checked 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. |
  257. | Cube | It 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. |
  258. | Jilebi | Checked 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. |
  259. | Cloudish | Checked 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. |
  260. | microsandbox cloud | The 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. |
  261. ### Keys and access surfaces
  262. | id | Key(s) | How the adapter connects |
  263. |---|---|---|
  264. | `e2b` | `E2B_API_KEY` | SDK `e2b` |
  265. | `daytona` | `DAYTONA_API_KEY` | SDK `@daytona/sdk` |
  266. | `modal` | `MODAL_TOKEN_ID`, `MODAL_TOKEN_SECRET` | SDK `modal` (gRPC) |
  267. | `vercel` | `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, `VERCEL_PROJECT_ID` (or `VERCEL_OIDC_TOKEN`) | SDK `@vercel/sandbox` |
  268. | `runloop` | `RUNLOOP_API_KEY` | SDK `@runloop/api-client` |
  269. | `freestyle` | `FREESTYLE_API_KEY` | SDK `freestyle` |
  270. | `blaxel` | `BL_API_KEY`, `BL_WORKSPACE` | SDK `@blaxel/core` |
  271. | `northflank` | `NORTHFLANK_TOKEN`, `NORTHFLANK_PROJECT` | SDK `@northflank/js-client` |
  272. | `cloudflare` | `CLOUDFLARE_SANDBOX_URL`, `CLOUDFLARE_SANDBOX_TOKEN` | REST, to the bridge Worker in templates/cloudflare-worker |
  273. | `instabox` | `INSTABOX_API_KEY` | REST api.instabox.sh |
  274. | `upstash` | `UPSTASH_BOX_API_KEY` | SDK `@upstash/box` |
  275. | `tenki` | `LUXOR_API_KEY` or `LUXOR_AUTH_TOKEN` (the old `TENKI_API_KEY` / `TENKI_AUTH_TOKEN` still work) | SDK `@tenkicloud/sandbox` (also published as `@luxorai/sandbox`) |
  276. | `boxlite` | `BOXLITE_API_KEY` | SDK `@boxlite-ai/boxlite` (native: macOS arm64, Linux glibc) |
  277. | `dedalus` | `DEDALUS_API_KEY` | REST dcs.dedaluslabs.ai/v1 |
  278. | `createos` | `CREATEOS_SANDBOX_API_KEY` | REST api.sb.createos.sh/v1 |
  279. | `quivvo` | `QUIVVO_API_KEY` | REST tryquivvo.com/api/v1 |
  280. | `celesto` | `CELESTO_API_KEY` | SDK `@celestoai/sdk` |
  281. | `agent37` | `AGENT37_API_KEY` | REST api.agent37.com/v1 + sandbox.agent37.app |
  282. | `boat` | `BOAT_API_KEY` | REST boat.dev/api/v1 |
  283. | `tensorlake` | `TENSORLAKE_API_KEY` | REST api.tensorlake.ai + `<id>.sandbox.tensorlake.ai` |
  284. | `buddy` | `BUDDY_TOKEN`, `BUDDY_WORKSPACE`, `BUDDY_PROJECT` (`BUDDY_REGION` for EU/AS) | REST api.buddy.works |
  285. | `boxd` | `BOXD_API_KEY` | SDK `@boxd-sh/sdk` (gRPC; there is no REST API) |
  286. | `maritime` | `MARITIME_API_KEY` | REST api.maritime.sh + the sandbox's data plane |
  287. | `promigence` | `PROMIGENCE_API_KEY` | REST api.promigence.ai/v1 |
  288. | `zode` | `ZODE_API_KEY` | REST api.zode.dev/v1 |
  289. | `boxcompute` | `BOXCOMPUTE_API_KEY` | REST api.boxcompute.ai/api/v2 |
  290. | `lizard` | `LIZARD_API_KEY`, `LIZARD_PROJECT_ID` | REST lizard.build/api |
  291. | `munito` | `MUNITO_API_KEY` | REST api.munito.ai/sandboxes/v1 |
  292. | `novita` | `NOVITA_API_KEY` (`NOVITA_DOMAIN` for another region) | SDK `e2b`, pointed at us-phx-1.sandbox.novita.ai |
  293. | `smol` | `SMOL_CLOUD_TOKEN` | REST api.smolmachines.com/v1 |
  294. | `isorun` | `ISORUN_API_KEY` | REST run-<region>.isorun.ai/v1 (region from the key) |
  295. | `instavm` | `INSTAVM_API_KEY` | REST api.instavm.io |
  296. | `prized` | `PRIZED_API_KEY` | REST api.prized.dev/api/v1 + the sandbox's edge |
  297. | `zipbox` | `ZIPBOX_API_KEY` | REST api.tribes.xyz + the box's own API |
  298. | `koyeb` | `KOYEB_API_TOKEN` | SDK `@koyeb/sandbox-sdk` |
  299. | `fly` | `FLY_API_TOKEN`, `FLY_APP` | REST api.machines.dev/v1 |
  300. | `sprites` | `SPRITES_TOKEN` | REST api.sprites.dev/v1 (the SDK needs Node 24) |
  301. | `morph` | `MORPH_API_KEY` | SDK `morphcloud` |
  302. | `together` | `TOGETHER_API_KEY` | SDK `together-sandbox` |
  303. | `depot` | `DEPOT_TOKEN` | SDK `@depot/sandbox` |
  304. | `namespace` | `NSC_TOKEN` | SDK `@namespacelabs/sdk` |
  305. | `lambda-microvm` | `LAMBDA_MICROVM_IMAGE` + AWS credentials | SDK `@aws-sdk/client-lambda-microvms`, plus execd (templates/aws-lambda-microvm) |
  306. | `thunder` | `TNR_API_TOKEN` | REST api.thundercompute.com:8443/v1, plus system `ssh` |
  307. | `exedev` | `EXE_API_TOKEN` (minted with `generate-api-key --cmds=new,ssh,rm,ls`) | REST `POST exe.dev/exec` |
  308. | `nanite` | `NANITE_API_KEY` | REST api.nanite.run/v1 |
  309. | `render` | `RENDER_API_KEY`, `RENDER_WORKSPACE_ID` | REST api.render.com/v1 + per-sandbox connect tokens |
  310. | `quave` | `QUAVEONE_USER_TOKEN`, `QUAVEONE_ACCOUNT_ID`, `QUAVEONE_APP_ID`, `QUAVEONE_SANDBOX_TEMPLATE_ID` | REST api.quave.cloud/api/public/v1 |
  311. | `beam` | `BEAM_TOKEN`, `BEAM_WORKSPACE_ID` | SDK `@beamcloud/beam-js` |
  312. | `mosaic` | `MOSAIC_API_TOKEN` | REST sandbox.mosaicos.com/v1 |
  313. | `nodus` | `NODUS_API_KEY`, `NODUS_PROJECT` | REST api.nodus-compute.ai/apis/nodus.dev/v1 |
  314. | `cathedral` | `CATHEDRAL_API_KEY` | REST cathedral.computer/v1 |
  315. | `keln` | `KELN_API_KEY` | REST sandbox.keln.ai/v1 (commands stream as SSE) |
  316. | `mandala` | `MANDALA_API_KEY` | REST app.mandala.computer/api/v1 |
  317. | `platinum` | `PT_TOKEN` (`PT_API_URL` for a self-hosted control plane) | REST api.platinum.dev/v1 |
  318. | `inngest` | `INNGEST_SIGNING_KEY` (`INNGEST_ENV` for a branch environment) | REST api.inngest.com/v2/sandboxes, the calls the `inngest` SDK makes |
  319. | `archil` | `ARCHIL_API_KEY` (`ARCHIL_REGION`, default `aws-us-east-1`) | REST control.&lt;region&gt;.archil.com/api for the lifecycle; SDK `disk` (Node 22.19+) for commands |
  320. | `openpond` | `OPENPOND_API_KEY` | REST api.openpond.ai/v1/sandboxes, the calls `openpond-sdk` makes |
  321. | `gmi` | `GMI_SANDBOX_API_KEY`, `GMI_SANDBOX_TEMPLATE` (an Agent template id or name) | REST console.gmicloud.ai/api/v2 + the sandbox's data plane |
  322. | `dory` | `DORY_API_KEY` | REST api.dory.run/v1 + data.dory.run |
  323. | `groundbox` | `GROUNDBOX_API_KEY` | REST api.groundbox.dev/v1 |
  324. | `briq` | `BRIQ_API_KEY` | REST api.briq.cloud/v1 |
  325. | `kubi` | `KUBI_API_KEY` | REST api.trykubi.com/v1 |
  326. | `orble` | `ORBLE_API_KEY` | REST orble.tech/v1 |
  327. | `runtime` | `RUNTIME_API_KEY` | REST api.withruntime.com/v2 |
  328. | `digitalocean` | `DIGITALOCEAN_TOKEN` | REST api.digitalocean.com/v2/harness-runtime |
  329. | `docker-cloud` | `DOCKER_ID`, `DOCKER_PAT` (with Cloud Sandboxes access) | REST connect.docker.com/sandboxes/v1 + the sandbox's endpoint |
  330. | `superserve` | `SUPERSERVE_API_KEY` | REST api.superserve.ai + sandbox.superserve.ai (per-sandbox access token) |
  331. | `eqvps` | `EQVPS_API_KEY` | REST api.eqvps.com/api/v1/eqvps |
  332. | `solari` | `SOLARI_API_KEY` | REST api.getsolari.com (exec and signed file URLs; no WebSocket) |
  333. | `pilldrops` | `PILLDROPS_API_KEY` | REST pilldrops.com/v1 |
  334. | `vers` | `VERS_API_KEY` | REST api.vers.sh/api/v1 |
  335. | `oblien` | `OBLIEN_CLIENT_ID`, `OBLIEN_CLIENT_SECRET` | REST api.oblien.com/v1 + the vm.oblien.com runtime gateway (short-lived JWT) |
  336. | `runta` | `RUNTA_API_KEY` | REST api.runta.com/v2, exec through SDK `@runta/runta-sdk` (WebSocket) |
  337. | `stateset` | `STATESET_API_KEY` | REST api.sandbox.stateset.app/api/v1 |
  338. | `saas-sandbox` | `AAS_API_KEY` | REST sandbox-as-a-service.com/v1 |
  339. | `sandbox0` | `SANDBOX0_TOKEN` | REST api.sandbox0.ai/api/v1 |
  340. | `watasu` | `WATASU_API_KEY` (`options.team` for a shared team) | REST api.watasu.io/v1, exec through SDK `@watasu/sdk` (WebSocket) |
  341. | `langsmith` | `LANGSMITH_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 |
  342. | `miosa` | `MIOSA_API_KEY` | REST api.miosa.ai/api/v1 |
  343. | `railway` | `RAILWAY_TOKEN` (project token), or `RAILWAY_API_TOKEN` + `RAILWAY_ENVIRONMENT_ID` | GraphQL backboard.railway.com/graphql/v2 |
  344. | `agentbay` | `AGENTBAY_API_KEY` (`AGENTBAY_REGION`, `AGENTBAY_IMAGE_ID` optional) | REST (OpenAPI RPC) agentbay.&lt;region&gt;.aliyuncs.com |
  345. | `tencent` | `TENCENT_AGS_API_KEY`, `TENCENT_AGS_TOOL` (`TENCENT_AGS_REGION` optional) | SDK `e2b`, at &lt;region&gt;.tencentags.com |
  346. | `workpaper` | `WORKPAPER_API_KEY` (from `workpaper keys create`) | REST api.workpaper.co/v1/computers |
  347. | `rayrun` | `RAYRUN_TOKEN` (console API token) | REST api.rayrunos.com/v1 |
  348. | `tama` | `TAMA_TOKEN` | gRPC-Web gateway.tama.computer (api.v1.ApiService), hand-encoded protobuf |
  349. | `tangle` | `TANGLE_API_KEY` | REST sandbox.tangle.tools/e2b (its plain-HTTP routes) |
  350. | `nirvana` | `NIRVANA_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 |
  351. | `agental` | `AGENTAL_API_KEY` | REST agental.io/v1 |
  352. | `volcengine` | `VOLCENGINE_E2B_API_KEY`, `VOLCENGINE_E2B_TEMPLATE_ID` (`VOLCENGINE_E2B_REGION` optional) | SDK `e2b`, at api.vefaas-e2b.sandbox-&lt;region&gt;.volcapig.com |
  353. | `openreward` | `OPENREWARD_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 |
  354. | `baseten` | `BASETEN_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 |
  355. | `chalk` | `CHALK_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 |
  356. | `voidrun` | `VOIDRUN_API_KEY` | REST api.void-run.com/api |
  357. | `kosa8` | `KOSA8_API_KEY` | REST api.kosa8.com/v1 |
  358. | `primeintellect` | `PRIME_API_KEY` (with the `sandbox` scope; `PRIME_TEAM_ID` optional) | REST api.primeintellect.ai/api/v1/sandbox + the sandbox gateway (Connect stream for commands) |
  359. | `sandboxer` | `SANDBOXER_API_KEY` | REST sandboxer.com/api/v1 |
  360. | `cyqle` | `CYQLE_API_KEY` (`options.slotId` for a paid desktop) | REST api.cyqle.in/v1, then the desktop's region (api-us / api-eu) |
  361. | `islo` | `ISLO_API_KEY` | REST api.islo.dev/auth/token (key for a session token) + ca.compute.islo.dev |
  362. | `hyperbrowser` | `HYPERBROWSER_API_KEY` | REST api.hyperbrowser.ai/api + each sandbox's runtime URL and token |
  363. | `offstage` | `OFFSTAGE_API_KEY` | REST api.offstage.cloud/v1 |
  364. | `machine0` | `MACHINE0_API_KEY` (`MACHINE0_SSH_KEY_ID` optional) | MCP app.machine0.io/mcp (JSON-RPC `tools/call` over HTTP) |
  365. | `lightcone` | `TZAFON_API_KEY` | REST api.tzafon.ai |
  366. | `openci` | `OPENCI_URL`, `OPENCI_TOKEN` | REST /v1/sandboxes |
  367. | `opensandbox` | `OPEN_SANDBOX_DOMAIN`, optional `OPEN_SANDBOX_API_KEY` | REST /v1/sandboxes + execd in the sandbox |
  368. | `cloudrun` | `GOOGLE_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) |
  369. | `gke-agent-sandbox` | `AGENT_SANDBOX_K8S_API`, `AGENT_SANDBOX_ROUTER_URL`, `AGENT_SANDBOX_WARM_POOL` + `AGENT_SANDBOX_K8S_TOKEN` or Google credentials | Kubernetes API (SandboxClaim) + sandbox-router (gRPC-Web, REST) |
  370. | `azure-sandboxes` | `AZURE_SUBSCRIPTION_ID`, `AZURE_RESOURCE_GROUP`, `AZURE_SANDBOX_GROUP`, `AZURE_REGION` + `AZURE_ACCESS_TOKEN` or `AZURE_TENANT_ID`/`AZURE_CLIENT_ID`/`AZURE_CLIENT_SECRET` | REST management.{region}.azuredevcompute.io |
  371. | `docker` | none (`SBR_DOCKER=0` turns it off) | `docker` CLI |
  372. Provider SDKs are optional peer dependencies, loaded only when that provider is used:
  373. `npm install sandboxrouting e2b modal` installs the router plus two providers. A provider
  374. whose key is set but whose SDK is missing is skipped with an install hint.
  375. ## How a provider is chosen
  376. A **routing strategy** makes the choice, and you can switch it. The hard rules come first
  377. and are the same under every strategy, so no strategy can route around them. `sbr route`
  378. prints the ranked plan and why each provider sits where it does. `sbr route --compare`
  379. prints the plan under every strategy. The full design is in [docs/routing.md](docs/routing.md).
  380. | Strategy | Order |
  381. |---|---|
  382. | `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). |
  383. | `cheapest` | Any free usage by price, then your hardware, then paid by price. |
  384. | `balanced` | The `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. |
  385. | `fastest` | Unbilled 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. |
  386. | `spread` | The `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. |
  387. You pick a strategy three ways:
  388. - in config, with `"routing": { "strategy": "balanced" }`;
  389. - per request, with `strategy: "fastest"` (`--strategy`);
  390. - by registering your own with `router.registerStrategy({ name, description, rank })`.
  391. Within a lane, `priority` in config breaks ties first. The lanes keep paid usage **off by
  392. default**: with `allowPaid: false` nothing is ever billed, and a request no free tier can
  393. take fails with the reason for every provider. You can turn paid usage on globally or per
  394. provider. With `maxPaidUsdPerMonth` set, paid routing stops when the month's spend
  395. reaches it. Your own hardware (openci, OpenSandbox, local Docker) goes after the free lanes. With
  396. `selfHosted: "first"` it goes ahead of them, and with `"never"` it's removed.
  397. A provider is left out when:
  398. - it has no key, or it is disabled;
  399. - it lacks a capability in `needs` (`ports`, `pause`, `customImage`, `gpu`, `snapshot`,
  400. `extendTimeout`, `fileList`);
  401. - it can't run the requested `image`;
  402. - the timeout is over its maximum;
  403. - `execTimeoutSec` is over its per-command cap (exe.dev cuts commands off at 30 s);
  404. - its isolation is weaker than `minIsolation` (`container` < `gvisor` < `microvm`/`vm`);
  405. - it runs another operating system than the request's `os` (`linux` unless the request says
  406. `macos`; `offstage` is the macOS provider);
  407. - its circuit is open (see below);
  408. - neither free nor paid usage can take the request. Free fails when:
  409. - the tier is used up;
  410. - what's left won't cover the whole request;
  411. - its concurrency is full;
  412. - the timeout is over the free lifetime cap.
  413. Paid fails when it isn't allowed, or when the month's budget won't cover the whole
  414. request.
  415. Live sandboxes **reserve** what they can still spend: until their deadline, at their own
  416. size. So a free tier takes a request only if, after those reservations, it covers the full
  417. timeout at the size the provider will create. A paid request needs the same from the
  418. budget. Extending a sandbox (`sbr extend`) or resuming one reserves the time it adds under
  419. the same rule, or is refused. With `allowPaid: false`, no sandbox can run past its free tier,
  420. and `maxPaidUsdPerMonth` is a hard cap.
  421. The router re-checks the provider under the ledger lock when reserving. A request planned
  422. as free that loses the last free slot or credit to a parallel request moves on to the next
  423. provider. It never quietly becomes paid.
  424. If the chosen provider refuses, the router tries the next one, and the refusal changes what
  425. it does next:
  426. | Refusal | What happens next |
  427. |---|---|
  428. | 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. |
  429. | 429 | The 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. |
  430. | 401 or 403 | The provider is skipped for 10 minutes. |
  431. | Network errors and 5xx | The 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. |
  432. `sandbox.route` records every provider tried or skipped and why. `sbr providers` shows each
  433. provider's health: the success rate of recent creates and the circuit state. This health
  434. is computed from the last 50 outcomes whenever it is read, and `sbr reset <provider>`
  435. clears it.
  436. ### Metering
  437. No provider has an API that reports remaining free credit, which the research for this
  438. router confirmed. So the router meters locally. Every sandbox's running time is recorded as
  439. billing segments. Pausing closes a segment. A sandbox past its deadline is billed only up to
  440. the deadline. Cost is running time × (vCPU × vCPU price + GiB × GiB price), using the
  441. provider's prices or yours.
  442. Usage outside the router (the provider's console, another tool) isn't seen. For a one-time
  443. credit you have already spent part of, set `usedBeforeUsd`. If a provider refuses for quota
  444. anyway, the mark above catches it.
  445. Some providers bill the vCPUs only while they are busy (`pricing.billing: "active-cpu"`:
  446. Vercel, Cloudflare, Render, Upstash Box, Fly Sprites, boxd, SuperHQ Nanite, Tensorlake, Runtime,
  447. DigitalOcean Harness Runtime, Railway, smol).
  448. Strategies rank these by the expected cost, with the vCPUs busy `activeCpuShare` of the time
  449. (default 0.3; set `routing.activeCpuShare` for your workload, or
  450. `providers.<id>.pricing.activeCpuShare` for one provider), so `cheapest` compares them fairly.
  451. Reservations and metering still count every vCPU busy, since the router can't see CPU time: a
  452. busy box can't overrun a free tier or a budget, and the router stops using such a free tier a
  453. little before the provider would. Details in [docs/routing.md](docs/routing.md#active-cpu-billing).
  454. ## Jobs: work that moves between boxes
  455. A sandbox can die, its provider can refuse, or a free tier's limits can end it: a lifetime
  456. cap (E2B's free hour, Vercel's 45 minutes), running out of credit, the provider failing. A
  457. **job** keeps going through all of that. It is ordered steps plus a working directory. The
  458. workdir is checkpointed after each step, so the job continues on another box from where it
  459. stopped.
  460. ```ts
  461. const job = await router.jobs.run({
  462. sandbox: { image: "python:3.12-slim" }, // routed like router.create
  463. files: { "main.py": "print('hi')" }, // the initial workdir ($HOME/work)
  464. setup: [{ run: "pip install -q requests" }], // runs again on every new box
  465. steps: [
  466. { run: "python main.py > out.txt" },
  467. { run: "curl -fsS -X POST https://hooks.example/done", idempotent: false },
  468. ],
  469. });
  470. console.log(job.state, job.migrations, job.placements.map((p) => `${p.provider}:${p.endReason}`));
  471. ```
  472. - **Planned moves.** Before each step the job checks the box. If the box can't fit the next
  473. step, the job extends it when the provider allows that within the free lifetime cap;
  474. otherwise it moves. It also moves when the free credit won't cover the step and another
  475. provider ranks first, when a quota or auth refusal or an open circuit hits the box's
  476. provider, and, with `rebalance`, off a paid box when a free one is available.
  477. - **Unplanned losses.** If a box vanishes, its provider refuses, or errors repeat, the job
  478. moves to a new box and restores the last checkpoint. The step that was running runs
  479. again, but only if it is `idempotent` (the default). Steps with outside effects are
  480. marked `idempotent: false`, so the job fails rather than run them twice. A non-zero exit
  481. is the step's own failure unless it has `retries`. Exit 137 can move the job to a box
  482. with twice the memory (`growMemoryOnOom`).
  483. - **Crashes.** The process driving a job holds a lease. If it dies, the job reads as
  484. `orphaned` after 60 s, and `sbr job resume <id>` (or `sbr serve`, every 5 minutes)
  485. continues it from what the ledger recorded.
  486. - **Waiting.** When no provider can take the job now, it waits only if a reason lapses
  487. within `maxWaitSec`: a rate-limit mark, a circuit, or a full free tier whose next
  488. sandbox ends soon. Otherwise it fails at once with every provider's reason.
  489. Checkpoints live in `~/.sandboxrouting/checkpoints/` and are checked by SHA-256. When the
  490. job ends, the last one is the result: `sbr job download <id>` saves it.
  491. `router.move(id)` does the same move once for an interactive sandbox: it copies the workdir
  492. to a new box, then kills the old one. The design and every decision table are in
  493. [docs/routing.md](docs/routing.md).
  494. ## The four surfaces
  495. All four share one ledger (`~/.sandboxrouting/ledger.json`; `SBR_HOME` moves it). It is
  496. locked for every update and written whole, so the CLI, the REST server and an MCP server
  497. running at once agree on what is live and what is spent.
  498. **SDK:** `create`, `connect(id)`, `list`, `kill`, `status`, `plan`, `sweep`, `move(id)`,
  499. `strategies()`, `registerStrategy(s)`, and `jobs` (`run`, `submit`, `resume`, `get`, `list`,
  500. `cancel`, `workspace`, `sweep`). A sandbox has:
  501. - `commands.run(cmd, {cwd, env, timeoutSec, onStdout, onStderr})`
  502. - `files.read`, `files.readBytes`, `files.write`, `files.list`
  503. - `getUrl(port)`, `setTimeout(sec)`, `pause()`, `resume()`, `kill()`
  504. `connect("e2b:abc123")` adopts a sandbox created outside the router.
  505. **CLI:** `sbr --help`.
  506. ```bash
  507. sbr providers # free-tier status, health and circuit of every provider
  508. sbr check # live create/exec/files/kill on every configured free provider
  509. sbr route --needs ports # where a sandbox would go, and why the others were skipped
  510. sbr route --compare # the same request under every strategy
  511. sbr strategies # the strategies, and which one is active
  512. sbr run -- python3 -c 'print(42)' # create, run, kill; exit code passes through
  513. id=$(sbr create --image node:22 --timeout 900 --strategy fastest)
  514. sbr exec "$id" -- npm test
  515. sbr move "$id" # copy its workdir to a new box, kill the old one
  516. sbr kill "$id"
  517. sbr job run --step "make" --step "make test" # steps that survive losing a box
  518. sbr job status <job-id> # where it ran, why it moved, how each step ended
  519. sbr job download <job-id> # the final workdir, as a .tgz
  520. ```
  521. **REST API:** `sbr serve --port 8787`. Set `serverToken` in config (or `SBR_SERVER_TOKEN`)
  522. to require `Authorization: Bearer …`. The endpoints are listed at the top of
  523. [src/server/http.ts](src/server/http.ts): `POST /v1/sandboxes`,
  524. `POST /v1/sandboxes/{id}/exec`, `GET|PUT /v1/sandboxes/{id}/files?path=`,
  525. `GET /v1/providers`, `POST /v1/route[?compare=1]`, `GET /v1/strategies`,
  526. `POST /v1/sandboxes/{id}/move`, and the jobs: `POST /v1/jobs` (202 with the job's id; `?wait=1`
  527. to wait for the end), `GET /v1/jobs[/{id}]`, `POST /v1/jobs/{id}/resume|cancel`,
  528. `GET /v1/jobs/{id}/workspace`. Every 5 minutes the server reconciles with the providers,
  529. reaps boxes left behind by finished jobs, and resumes orphaned jobs. `POST /v1/sweep` does it
  530. on demand and returns `{ sandboxes, jobs }`.
  531. **MCP server:** `sbr mcp` (stdio). Its tools are `list_providers`, `list_strategies`,
  532. `create_sandbox`, `run_command`, `read_file`, `write_file`, `list_files`, `get_url`,
  533. `set_timeout`, `move_sandbox`, `list_sandboxes`, `kill_sandbox`, and for jobs `run_job`,
  534. `job_status`, `list_jobs`, `resume_job` and `cancel_job`. `run_job` waits up to `waitSec`,
  535. then returns the job's id to poll with `job_status`. For Claude Code:
  536. ```bash
  537. claude mcp add sandboxes -- npx -y sandboxrouting mcp
  538. ```
  539. Other clients take the same command (`npx -y sandboxrouting mcp`) in their MCP config, with
  540. your provider keys in its `env`. From a clone, `node /path/to/sandboxrouting/dist/cli.js mcp`
  541. runs the local build instead. The server is listed in the MCP Registry as
  542. `com.sandboxrouting/sandboxrouting`.
  543. ## AgentRun
  544. `sandboxrouting/agentrun` is a computer provider for [AgentRun](https://agentrun.ai/): one provider that gives an
  545. AgentRun server every sandboxrouting provider able to boot AgentRun's box image, routed free usage first, with
  546. failover. It implements AgentRun's `MachineHost` with the router in-process, as a dial host (the machine's
  547. `agentrun-dial` connects to the AgentRun server), and reports the provider it chose in the computer's labels.
  548. AgentRun keeps durable runs, cost caps and the run timeline. Tested against fake providers only, not yet against
  549. AgentRun's conformance suite or a live provider. See [docs/agentrun.md](docs/agentrun.md).
  550. ```ts
  551. import { create } from "sandboxrouting/agentrun"; // needs @parcha/agentrun-computer too
  552. const provider = create({ strategy: "free-first", providers: "daytona,modal,fly", dial });
  553. ```
  554. ## Configuration
  555. `./sandboxrouting.json`, else `~/.sandboxrouting/config.json`, or the path in `SBR_CONFIG`.
  556. Every field is optional. See [sandboxrouting.example.json](sandboxrouting.example.json):
  557. ```jsonc
  558. {
  559. "routing": { "strategy": "free-first" }, // cheapest | balanced | fastest | spread | yours
  560. "allowPaid": false, // SBR_ALLOW_PAID=1 for one run
  561. "maxPaidUsdPerMonth": 10,
  562. "selfHosted": "after-free", // "first" | "after-free" | "never"
  563. "defaults": { "timeoutSec": 300 },
  564. "providers": {
  565. "e2b": { "usedBeforeUsd": 12.5 },
  566. "daytona": { "freeTier": { "kind": "monthly-credit", "usd": 200 }, "priority": 10 },
  567. "modal": { "options": { "ports": [8080] } },
  568. "docker": { "isolation": "gvisor" }, // when Docker runs with runtime runsc
  569. "fly": { "enabled": false }
  570. },
  571. "jobs": { "maxMigrations": 5, "maxWaitSec": 300, "rebalance": false }
  572. }
  573. ```
  574. `routing` also takes `weights` for `balanced`, `circuitBreaker` settings, and
  575. `activeCpuShare`, the expected busy share of the vCPUs used to rank providers that bill only
  576. active CPU (default 0.3). A provider's `pricing` override takes `vcpuSecondUsd`,
  577. `gibSecondUsd`, `sandboxSecondUsd`, `billing` (`"wall"` or `"active-cpu"`) and
  578. `activeCpuShare`. `jobs` takes
  579. the checkpoint mode, limits and timeouts. Both are documented in
  580. [docs/routing.md](docs/routing.md#4-configuration-reference). `policy` still works as the
  581. old name for `routing.strategy`.
  582. `sbr reset <provider>` clears a provider's quota, rate-limit and auth marks, and its health
  583. history, after you top up or fix a key.
  584. ## Usage dashboard
  585. A router can report what its ledger records to a dashboard that shows how your workloads
  586. spread across providers: sandbox count, sandbox-hours and memory GiB-hours per day and
  587. provider, spend against the free usage each provider has left, refusals and failed creates,
  588. health and the circuit breaker, live sandboxes with their state as of now, and jobs with every
  589. move and why. It is two packages in this repository, both MIT: [back/](back) (an ingest and
  590. read API on Postgres) and [dashboard/](dashboard) (Next.js). Reporting is off unless you turn
  591. it on.
  592. ### Self-hosting
  593. ```bash
  594. cp deploy/.env.example deploy/.env # set POSTGRES_PASSWORD and SBR_ADMIN_TOKEN
  595. docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d --build
  596. ```
  597. That runs Postgres, back on port 8787 and the dashboard on port 3000. Sign in with
  598. `SBR_ADMIN_TOKEN`, then make an ingest key for each router under API keys (or set
  599. `SBR_INGEST_TOKEN` too). Each image is configured only by environment variables:
  600. | back | |
  601. |---|---|
  602. | `DATABASE_URL` | `postgres://…` (required). Migrations run at startup and only move forward. |
  603. | `SBR_ADMIN_TOKEN`, `SBR_INGEST_TOKEN` | Optional keys for the first account, made if missing and never brought back once revoked. At least 24 characters. |
  604. | `SBR_SWEEP_TOKEN` | Lets a cron call `POST /v1/sweep` for every account. |
  605. | `PORT` | Default 8787. |
  606. | dashboard | |
  607. |---|---|
  608. | `BACK_URL` | back as the dashboard's server reaches it (required). |
  609. | `BACK_PUBLIC_URL` | back as routers reach it, for the setup snippet. |
  610. | `PORT` | Default 3000. |
  611. Nothing has to run in the background: whatever changes with time (a sandbox past its deadline,
  612. a mark that lapsed, a job whose runner stopped) is worked out when the dashboard reads it, with
  613. the database's clock. The sweep only rolls up closed days so reads stay cheap; run it from any
  614. cron (`curl -X POST -H "authorization: Bearer $SBR_SWEEP_TOKEN" http://back:8787/v1/sweep`) or
  615. with the compose file's `sweep` profile. Without Docker, `cd back && npm run build &&
  616. DATABASE_URL=… node dist/main.js` and `cd dashboard && npm run build && BACK_URL=… npm start`;
  617. `node back/dist/cli.js account create <name>` makes an account and prints its admin key.
  618. ### Turning on the reporter
  619. ```bash
  620. export SBR_REPORT_URL=http://localhost:8787
  621. export SBR_REPORT_TOKEN=sbrk_… # an ingest key
  622. ```
  623. or in config:
  624. ```jsonc
  625. { "report": { "url": "https://back.example", "token": "sbrk_…", "metadataKeys": ["team"] } }
  626. ```
  627. `SBR_REPORT=0` turns it off for one run. `createRouter` (and so the CLI, REST server and MCP
  628. server) reports when it is on; for a router you construct yourself, wrap its ledger with
  629. `reportingLedger`. Only ids, provider ids, sizes, times, states and prices leave the machine,
  630. plus the metadata keys you list. Never commands, env, file contents, provider error messages
  631. or keys.
  632. After every ledger write, and when a router starts, the reporter compares the ledger with what
  633. it last queued and queues an event for each thing that changed, in an outbox at
  634. `$SBR_HOME/report/outbox.json` (written whole, under a lock, like the ledger). Each event keeps
  635. its id until back acknowledges it, and back keeps the newest state of each sandbox, job and
  636. mark whatever order events arrive in, so a resend never counts twice. Routing never waits on
  637. back: a send times out after 4 s, and a failure backs off (recorded in the outbox, so other
  638. processes don't each retry a back end that is down) until the next router to start, or the
  639. same long-running one, delivers what is queued. Several quick changes may reach back as one
  640. state; the billing segments in it are complete.
  641. ## Adding a provider
  642. A provider is one file. Only `create`, `exec` and `kill` are required. The router
  643. implements file read, write and listing on top of `exec` (base64 in chunks, so binary is
  644. safe), and an adapter that can do better adds the native calls.
  645. ```ts
  646. // src/providers/acme.ts
  647. import { defineProvider, httpJson } from "./util.js";
  648. export const acmeProvider = defineProvider({
  649. info: {
  650. id: "acme",
  651. name: "Acme Sandboxes",
  652. homepage: "https://acme.dev",
  653. env: ["ACME_API_KEY"],
  654. capabilities: ["customImage"],
  655. freeTier: {
  656. tier: { kind: "monthly-credit", usd: 10 },
  657. concurrency: 5,
  658. source: "https://acme.dev/pricing",
  659. checked: "2026-11-11",
  660. },
  661. pricing: { vcpuSecondUsd: 0.00001, gibSecondUsd: 0.000003, defaultCpu: 1, defaultMemoryMiB: 1024 },
  662. },
  663. async create(spec, ctx) {
  664. const s = await httpJson<{ id: string }>("https://api.acme.dev/v1/sandboxes", {
  665. headers: { authorization: `Bearer ${ctx.env.ACME_API_KEY}` },
  666. body: { image: spec.image, timeout: spec.timeoutSec, env: spec.env, metadata: spec.metadata },
  667. });
  668. return { providerSandboxId: s.id };
  669. },
  670. async exec(id, command, opts, ctx) { /* … */ return { stdout: "", stderr: "", exitCode: 0 }; },
  671. async kill(id, ctx) { /* … */ },
  672. });
  673. ```
  674. Then add it to [src/providers/index.ts](src/providers/index.ts), or call
  675. `router.register(acmeProvider)` from your own code. To finish:
  676. - Add `listAlive` so `sbr sweep` can close sandboxes that died behind the router's back.
  677. - If the provider keeps a sandbox alive past the requested timeout, set
  678. `enforcesTimeout: false` in `info`. The router then deletes it at the deadline.
  679. - Make `create` throw errors with an HTTP `status`, so quota (402) and rate limits (429)
  680. fail over correctly. If the provider uses a status that means something else (a spent
  681. allowance as 429 or 409, a plan limit as 403), declare it with `refusals()` in
  682. `src/providers/util.ts`.
  683. - If the provider bills the vCPUs only while they are busy, set `billing: "active-cpu"` in
  684. `pricing` (and `activeCpuFloor` if it bills a minimum share), so strategies rank it by its
  685. expected cost.
  686. - Run the tests: `test/providers.test.ts` checks that every built-in declares its
  687. free-tier source and backs each capability it claims.
  688. ## Providers with extra setup
  689. - **Cloudflare** has no hosted sandbox API: a sandbox is a Durable Object plus the
  690. Container it starts, inside your own Worker. Deploy the bridge in
  691. [templates/cloudflare-worker](templates/cloudflare-worker) (`npm install`, then
  692. `npx wrangler secret put SANDBOX_TOKEN` and `npx wrangler deploy`). Then set
  693. `CLOUDFLARE_SANDBOX_URL` to the Worker's URL and `CLOUDFLARE_SANDBOX_TOKEN` to the same
  694. secret. The bridge uses `@cloudflare/sandbox` 1.x and destroys each container at its
  695. deadline with a Durable Object alarm. The sandbox size is the `instance_type` in
  696. `wrangler.jsonc`.
  697. - **No timeout of their own.** These providers don't stop a sandbox at the requested
  698. timeout:
  699. - Fly Sprites, Celesto, BoxLite, Dedalus, CreateOS, exe.dev and Agent37 have no TTL.
  700. - A Northflank service restarts its container when it exits.
  701. Their adapters declare `enforcesTimeout: false`, so the router deletes the sandbox at
  702. the deadline itself. `sbr sweep` (run every 5 minutes by `sbr serve`) deletes any it
  703. missed.
  704. - **AWS Lambda MicroVMs** have no exec API. Build the image in
  705. [templates/aws-lambda-microvm](templates/aws-lambda-microvm): its dependency-free
  706. `execd.mjs` runs commands and moves files behind the VM's endpoint. Then set
  707. `LAMBDA_MICROVM_IMAGE` to the image ARN.
  708. - **Google Cloud Run sandboxes** have no API of their own. Build the image in
  709. [templates/cloud-run-sandbox](templates/cloud-run-sandbox) and set `CLOUD_RUN_SANDBOX_IMAGE`;
  710. the region must offer Cloud Run instances (not `us-central1`, `us-east1` or `europe-west1`).
  711. - **GKE Agent Sandbox** needs [agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox)
  712. installed with its extensions, a `SandboxWarmPool` whose pods run sandboxd, and the
  713. sandbox-router exposed outside the cluster. A cluster CA that Node doesn't trust goes in
  714. `NODE_EXTRA_CA_CERTS`.
  715. - **Azure Container Apps Sandboxes** need a sandbox group (`Microsoft.App/sandboxGroups`).
  716. The default image is the public `ubuntu` disk image; `options.image` names another public
  717. one, and a template (`--template azure-sandboxes=<disk image id>`) uses your own.
  718. - **Thunder Compute** runs commands over SSH only. The adapter generates a throwaway key,
  719. gets a certificate from the API, and uses the system `ssh` and `ssh-keygen`. Sandbox
  720. access is enabled through Thunder's sales team.
  721. - **exe.dev** has one API endpoint, `POST /exec`, which takes SSH command text and cuts
  722. each call off at 30 seconds. Mint a token that may run `new`, `ssh`, `rm` and `ls`.
  723. - **Access gates:** Dedalus Machines needs beta access (403 until admitted), and Quivvo
  724. puts new free accounts in a queue.
  725. - **Together and Morph** boot from snapshots. When you give an `image` (or nothing), the
  726. adapter builds the snapshot once per image or size and reuses it. A `template`
  727. (`--template together=<alias>`) skips that step.
  728. - **Fly Machines** needs an app you own (`FLY_APP`).
  729. - **Northflank** needs a project (`NORTHFLANK_PROJECT`).
  730. - **Nirvana Labs** runs sandboxes on a sandbox cluster you create first (dashboard, or
  731. `POST /v1/sandbox_clusters` with an instance type, node count and region). Its nodes are
  732. billed by the hour from then on, sandboxes or not. Set `NIRVANA_SANDBOX_CLUSTER_ID` once
  733. its status is `ready`.
  734. - **Workpaper, Rayrun and tama** keep a stopped or idle machine instead of deleting
  735. it (Workpaper pauses after an idle hour, Rayrun cold-stops at `max_lifetime_seconds`, tama
  736. stops at its idle `ttl`), so they declare `enforcesTimeout: false` too. A new Rayrun sandbox
  737. has no network by default: the adapter opens egress, and `options.egress: "closed"` keeps
  738. it shut. Its default image is `ubuntu@1` (`options.agent` or a template names another).
  739. ## Checking providers live
  740. Each cloud adapter is type-checked against that provider's real SDK. The HTTP-only adapters
  741. (`cloudflare`, `sprites`) are tested against servers that speak their wire formats. A live
  742. run still needs your keys: set them, then run
  743. ```bash
  744. sbr check # every configured provider that has free usage left
  745. sbr check --provider koyeb # a paid-only provider runs only when you name it
  746. ```
  747. Each provider gets one small sandbox: it runs a command, writes, reads back and lists a
  748. file, then kills the sandbox. The check prints `ok` or the provider's own error.
  749. ## Development
  750. ```bash
  751. npm install
  752. npm run lint # ESLint over the whole repository (each check runs through hushrun)
  753. npm run typecheck # adapters are checked against the real provider SDK types
  754. npm test # the Docker ones run real containers when Docker is up
  755. npm run simulate # compare the routing strategies on a simulated month
  756. npm run build && node dist/cli.js providers
  757. ```
  758. back/ and dashboard/ are npm workspaces with their own checks: `npm run lint|typecheck|test|build
  759. -w back` (or `-w dashboard`). back's tests run on PGlite, a real Postgres in WebAssembly;
  760. `TEST_DATABASE_URL=postgres://…` runs them on a Postgres server instead, each test in its own
  761. database. `cd back && DATABASE_URL=pglite:memory npm run dev` starts back with nothing to set up.
  762. CI runs lint, typecheck and the tests through [hushrun](https://hushrun.com), which skips
  763. what this exact code already passed: a test file that passed on the exact files it read
  764. doesn't run again. See [CONTRIBUTING.md](CONTRIBUTING.md) to send a change, and
  765. [SECURITY.md](SECURITY.md) to report a vulnerability.
  766. ## Providers' names and terms
  767. sandboxrouting isn't affiliated with or endorsed by any provider it supports. Their names
  768. are trademarks of their owners. Free tiers and prices are as each adapter's `source` page
  769. said on its `checked` date, and they change: check a provider's own terms before you rely
  770. on them, and override them in config (`providers.<id>.freeTier`, `pricing`) when yours
  771. differ.
  772. ## License
  773. [MIT](LICENSE)
  774. The sandboxrouting name and logo are not covered by the MIT license.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.