Repository avatar
AI Tools
v0.1.0
active

throwbox

io.github.ejackson-vp/throwbox

Run one shell command in a disposable Linux box, paid in USDC over x402. No account.

Documentation

sandbox

ci codeql docs OpenSSF Scorecard coverage release

latest release MIT status: alpha go 1.26 node >= 24

runtime: Kata microVMs payments: x402 commands sealed client-side no accounts

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.

Terminal recording: pay, create, exec, upload, run, download, destroy

Unedited recording of make demo-session against a local kind cluster.

Warm session readyExec round tripCold start (image cached)Idle cost per guest
127 ms p5053 ms p502.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

  1. Pay. POST /v1/sessions answers 402 with a price. A signed payment is the entitlement, so there is no account to create.
  2. Provision. The controller runs one Kata microVM per session, from the warm pool or cold.
  3. Run. Commands and files are sealed to the guest's ephemeral key. The API, controller and relay move opaque frames and cannot read them.
  4. 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

ClaimHow it is enforced
The lease ends on timeGuest watchdog, controller deadline and activeDeadlineSeconds, independently
Commands and files stay privateSealed client-side to the guest; the API, controller and relay only route ciphertext
Nothing can dial inThe guest dials out to the relay; egress only through an allowlisting proxy on 443
Isolation is a VM, not a containerOne 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

Metricnp50p95
Warm server ready (pool = 20)50127 ms286 ms
Warm client ready50395 ms708 ms
Existing-session exec5053 ms108 ms
Cold server ready (image cached)102.69 s3.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

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.

NPM
throwbox-mcp
Install Command
npm install throwbox-mcp