
throwbox
io.github.ejackson-vp/throwbox
Run one shell command in a disposable Linux box, paid in USDC over x402. No account.
Documentation
Pay once with x402, get a temporary Linux machine. No account, no API key, no signup, and the control plane never sees what you run.
Unedited recording of make demo-session against a local kind cluster.
| Warm session ready | Exec round trip | Cold start (image cached) | Idle cost per guest |
|---|---|---|---|
| 127 ms p50 | 53 ms p50 | 2.69 s p50 | ~182 MiB |
Kata on two nodes with a 20-guest warm pool, control 0.1.16 (measured 2026-11-09); p50 unless stated. Method and caveats.
Why
Agent tool calls are untrusted code, and most sandboxes require an account and hand the operator your plaintext commands. This does the opposite: the payment is the identity, and commands and files are sealed client-side to the guest, so the API, controller and relay only route ciphertext.
Good fits: agent tool execution, CI and build isolation, code-runner backends, one-off data jobs that should not touch your laptop.
How it works
- Pay.
POST /v1/sessionsanswers402with a price. A signed payment is the entitlement, so there is no account to create. - Provision. The controller runs one Kata microVM per session, from the warm pool or cold.
- Run. Commands and files are sealed to the guest's ephemeral key. The API, controller and relay move opaque frames and cannot read them.
- Destroy. The lease ends, the pod is deleted, and the memory-backed workspace disappears with it.
sequenceDiagram
autonumber
participant C as Client
participant A as API
participant K as Controller / relay
participant G as Guest microVM
C->>A: POST /v1/sessions
A-->>C: 402 + price
C->>A: signed payment
A->>K: entitlement
K->>G: provision pod, start guest
G->>K: outbound WebSocket + key binding
K-->>C: key binding, relayed
C->>A: sealed command
A->>K: opaque envelope
K->>G: opaque frame
G-->>C: sealed result, relayed
The lease starts at READY and is immutable: the guest watchdog, the controller
deadline and activeDeadlineSeconds enforce it independently.
More: architecture · sessions · warm pool.
What holds, and what does not
| Claim | How it is enforced |
|---|---|
| The lease ends on time | Guest watchdog, controller deadline and activeDeadlineSeconds, independently |
| Commands and files stay private | Sealed client-side to the guest; the API, controller and relay only route ciphertext |
| Nothing can dial in | The guest dials out to the relay; egress only through an allowlisting proxy on 443 |
| Isolation is a VM, not a container | One Kata microVM per session, on tainted, default-deny nodes |
What this is not: no hardware attestation, no mainnet payments, no accounts. The threat model spells out what that costs, and production readiness lists the gap to a hosted service.
Try it
Prerequisites: Docker, kind, kubectl, Cilium CLI, Node >= 24, Go >= 1.26.
make up # kind + Cilium + images + deploy (~2 min)
make demo-session # pay, create, exec, upload, run, download, destroy
make dev-scale 2 # relay + egress-proxy at N replicas; bare `make dev-scale` prints the counts
make down
make dev-scale N is the multi-replica validation path: it patches
RELAY_REPLICAS/PROXY_REPLICAS, scales both StatefulSets, restarts the control
plane and waits for the rollout. It is idempotent, and make deploy resets it to
the committed values. The committed manifests run the relay at two shards (each
holding a disjoint half of the sessions, so a single pod restart costs one shard
rather than all of them) and the egress proxy at one. The controller stays at one
replica (ADR 0010).
Local clusters use runc, not microVMs. The demo exercises the same API, relay
and guest as a real deployment.
The control plane keeps payments and session state in Postgres 17, deployed by
the same manifests and reachable only from the controller
(ADR 0010). There is no SQLite path:
make up generates the database credentials into the git-ignored
deploy/kubernetes/02-secrets-dev.yaml, and backups are the database layer's
job, not the controller's (backup-restore.md).
Without a cluster, most of the system is testable in under a minute:
npm ci
make verify # build, typecheck, structure lint, unit + property + portable + go tests
make test # adds integration tests against the real guest binary
make security-test runs the packet-level isolation suite against a live
cluster. make guest && npm run test:coverage prints coverage for the unit and
property suites; the README badge merges those with the integration and fuzz
runs (scripts/coverage-merge.mjs).
Interfaces
sandbox run -- python3 --version # one-shot: create, run, destroy
sandbox create --tier standard # 5 minutes, 1 vCPU, 1 GiB
sandbox exec <id> -- python3 --version
sandbox run --file data.csv=data.csv --return out.csv -- python3 analyze.py
sandbox upload <id> ./src /workspace/src # directory -> tar
sandbox download <id> /workspace/out.txt ./out.txt
sandbox destroy <id>
Tiers: short (60 s), standard (300 s), extended (900 s), long (1800 s),
plus --duration, --cpu, --memory, --disk within platform caps.
import { SandboxClient, FileSessionStore } from "@x402s/sdk";
const client = new SandboxClient({ apiUrl, paymentMode: "mock", store: new FileSessionStore() });
const session = await client.createSession({ tier: "standard" });
await client.waitForReady(session);
const result = await client.exec(session, { command: ["python3", "--version"] });
await client.destroy(session);
// One-shot: fresh session, upload, exec, collect, destroy (files are
// workspace-relative). `runtime` is base | python | node, default base.
const run = await client.run({
runtime: "base",
command: ["bash", "-c", "python3 main.py > out.txt"],
files: { "main.py": "print('hello')" },
returnFiles: ["out.txt"],
});
console.log(run.exitCode, run.stdout, run.files["out.txt"]);
@x402s/sdk builds from source (npm ci && npm run build), not npm.
HTTP API
POST /v1/sessions # x402-protected; body has no plaintext
POST /v1/sessions/{id}/operations # { requestId, envelope }; op is inside
GET /v1/sessions/{id}/operations?request=… # encrypted get/list/stat
DELETE /v1/sessions/{id} # destroy now
All session endpoints require X-Sandbox-Capability. Reference:
docs/api.md · docs/cli.md.
Performance
| Metric | n | p50 | p95 |
|---|---|---|---|
| Warm server ready (pool = 20) | 50 | 127 ms | 286 ms |
| Warm client ready | 50 | 395 ms | 708 ms |
| Existing-session exec | 50 | 53 ms | 108 ms |
| Cold server ready (image cached) | 10 | 2.69 s | 3.33 s |
0.1.16 caches the x402 challenge for repeat creates and removes a redundant capacity round trip; warm client ready fell from 665 ms to 395 ms (p50, steady client with the challenge cached) and the server side from 179 ms to 127 ms.
These numbers were taken on 0.1.16. On 0.1.22 the same 50-sample harness measured 292-354 ms server and 548-595 ms client across two runs, so treat this table as the baseline, not a current promise. Issue #116 tracks the regression.
60 concurrent held sessions and 25/25 burst creates completed with zero failures; the bottleneck is the create queue at ~1.3/s, not VM boot. Sources: cluster numbers · engineering notes · harness.
Lab notebook
Three things the benchmarks changed my mind about:
- The VM was never the bottleneck. 127 ms server-side against 395 ms client-side, so ~268 ms is paid create and polling. That gap is the product target. Read more
- Bursts queue, they do not thrash. 25 simultaneous creates finished 25/25 in 19 s, which is exactly the ~1.3 creates/s the queue allows. Latency grows predictably and nothing fails. Read more
- A warm pool costs memory, not time. ~182 MiB per idle guest, about 3.6 GiB for a pool of 20 across two nodes, which is why pool size is a knob. Read more
Documentation
- New here: quickstart · architecture
- Security reviewer: guarantees · threat model · networking
- Operator: Talos deploy · capacity model · production readiness
- Contributor: ADRs · CONTRIBUTING.md
Full index: docs/README.md.
Status
Alpha. A reference deployment, not a hosted service: payments are mock or testnet, and there is no hardware attestation. What is missing, in order: docs/production-readiness.md. What comes next: ROADMAP.md.
Current limitations: no memory snapshots (filesystem checkpoints only), no GPUs, no arbitrary OCI images, mock or testnet payments only, and checkpoints are plaintext on disk (see docs/adr/0007).
Non-goals: a hosted commercial service, accounts, managed wallets, mainnet payments, hardware-attestation claims, feature parity with general-purpose sandbox platforms, and application-specific integrations. It does not ship a coding agent; callers may run one. Prepared runtimes and stateful sessions are in scope; a full IDE or dev-platform is not.
throwbox-mcpnpm install throwbox-mcp