# throwbox > Pay once with x402, get a temporary Linux machine. No account, no API key, no signup. The control plane routes sealed commands and files, and the machine is destroyed when the lease ends. **throwbox** is a hosted beta at `https://api.throwbox.dev`. Payments there are **real USDC on Base** (`eip155:8453`), settled through the Coinbase CDP facilitator, priced per session. The price comes from `GET /v1/pricing` rather than from this document. There are no accounts and no stored balance: the payment is the identity, and one payment buys one session. The source is MIT and self-hostable; `deploy/overlays/throwbox` is the public deployment. Free access is by invitation. The beta is one operator, one region, one control-plane node and one Postgres primary. Sessions are ephemeral. There is no suspend and no resume: the workspace is an `emptyDir` that dies with the pod, and nothing you write outlives the lease. Checkpoint storage in this repository is plaintext, which is why the hosted beta does not sell checkpoints. Isolation between sessions is a Kata microVM: each guest runs its own kernel, cannot reach another session, the Kubernetes API, a node, the metadata endpoint or a Service VIP, and reaches the internet only through the egress proxy. That is not a hardware root of trust, no escape attempt has been made, and there is no hardware attestation and no SLA. - Source: - Licence: MIT - Status: beta, hosted, one operator, one region - Hosted API base: `https://api.throwbox.dev` - Local API base: `http://localhost:8080` - Payment: real USDC on Base, per session, through the CDP facilitator - Accounts: none. No stored balance, no top-up, no refund credit - Sessions: ephemeral. No suspend, no resume, no persistence - Live pricing: `GET https://api.throwbox.dev/v1/pricing` This repository's CLI and SDK build `mock` and `testnet` payments only, so a mainnet payer client is still yours to write: do not point the `testnet` payer at the hosted service, and do not hardcode a price. If your wallet is on the invitation allowlist, a create is free up to a tier and concurrency ceiling the operator sets, and no payment header is needed. ## Start here - [Quickstart](https://github.com/ejackson-vp/sandbox/blob/main/docs/quickstart.md): the shortest path from zero to a paid session through the SDK. - [Architecture](https://github.com/ejackson-vp/sandbox/blob/main/docs/architecture.md): components, warm pool, relay and request path. - [CLI and SDK](https://github.com/ejackson-vp/sandbox/blob/main/docs/cli.md): every command and client method. - [HTTP API](https://github.com/ejackson-vp/sandbox/blob/main/docs/api.md): routes, envelopes, status codes. - [Security guarantees](https://github.com/ejackson-vp/sandbox/blob/main/docs/security-guarantees.md): what is enforced and what is not. - [Threat model](https://github.com/ejackson-vp/sandbox/blob/main/docs/threat-model.md): STRIDE by component. - [Production readiness](https://github.com/ejackson-vp/sandbox/blob/main/docs/production-readiness.md): the ordered gap between the hosted beta and a production service. - [Workload compatibility](https://github.com/ejackson-vp/sandbox/blob/main/docs/workload-compatibility.md): what actually runs in the guest. ## What an agent should do Use the CLI or the SDK. Do not hand-roll the sealed envelopes, the x402 payment, or the key exchange. The cryptography is load-bearing and easy to get subtly wrong. 1. Build the project: `npm ci && npm run build`. 2. Prefer the one-shot path for a single task: `sandbox run --json ...`. 3. For multi-step work, create a session, run operations, then destroy it in a `finally` block. 4. Collect outputs before the lease ends. Nothing survives termination, and there is no suspend to park work in. 5. Treat command failures as data, not transport errors. Results carry `ok: false` and a stable `error.code`. ### When a create is refused - `402` means a price is owed, not that you were charged. Nothing settles until you sign the `PAYMENT-REQUIRED` header and retry with `PAYMENT-SIGNATURE`. One payment buys one session; the same payment replayed returns that session instead of billing again. If you are not the payer, stop and tell the human. - `429` with `rate_limited` means slow down. Honour `Retry-After`, retry once, and do not raise parallelism: one foreground operation per session is the rule, and the limits below bound the rest. - `429` with `creates_disabled` means the operator has turned new sessions off. Stop. Do not retry, do not re-sign, and do not try the same payment against another session. Wait for the operator to restore it. ### Install and build ```bash git clone https://github.com/ejackson-vp/sandbox.git cd sandbox npm ci npm run build node cli/dist/index.js --help # optional, puts `sandbox` on PATH npm link -w @x402s/cli ``` The CLI stores each session handle in `~/.config/x402-sandbox/.json` with mode `0600`. Set `X402_SANDBOX_HOME` to move it. The file contains the session id, capability and client key pair. ### One-shot run (preferred for agents) ```bash sandbox run --json \ --file data.csv=data.csv \ --file analyze.py=analyze.py \ --return out.csv \ -- python3 analyze.py ``` This creates a fresh session, uploads the files, runs the command, downloads the requested outputs, and always destroys the session. File paths are workspace-relative; `/workspace` is implied. - Only the `base` runtime exists today. Anything else fails with `unsupported_runtime` before a session is created. - `--return` writes the downloaded file to the same relative path in the current directory. - `--timeout` bounds the command. - `--json` is the machine-readable form. `--quiet` suppresses progress notes. ### Sessions and commands ```bash sandbox create --tier standard sandbox status sandbox exec -- python3 --version sandbox exec --env GREETING=hi -- bash -c 'echo "$GREETING"' sandbox exec --timeout 5s -- bash -c 'sleep 60' # exits 124 sandbox upload ./src /workspace/src # directory -> tar sandbox download /workspace/out.txt ./out.txt sandbox download /workspace/src ./src --extract sandbox ls /workspace --recursive sandbox stat /workspace/out.txt sandbox destroy ``` Custom limits: ```bash sandbox create --duration 15m --cpu 2 --memory 2Gi --disk 2Gi ``` ### SDK ```ts import { SandboxClient } from "@x402s/sdk"; const client = new SandboxClient({ apiUrl: "http://localhost:8080", // local. The hosted API is https://api.throwbox.dev paymentMode: "mock", }); const run = await client.run({ runtime: "base", // optional, currently the only runtime command: ["bash", "-c", "python3 analyze.py > out.csv"], files: { "analyze.py": "print('hello')" }, // workspace-relative returnFiles: ["out.csv"], tier: "short", }); console.log(run.sessionId, run.exitCode, run.stdout); console.log(Buffer.from(run.files["out.csv"]).toString()); ``` `run` always destroys the session. For a long-lived handle: ```ts const session = await client.createSession({ tier: "standard" }); await client.waitForReady(session); const result = await client.exec(session, { command: ["python3", "--version"] }); await client.destroy(session); ``` `SandboxError` is thrown for transport or session problems. Command failures come back as results with `ok: false`. ## HTTP flow There are no accounts, cookies or API keys. A paid session is accessed with a short-lived capability token: ```http X-Sandbox-Capability: ``` The server stores only `SHA-256(capability)`, scoped to one session id and valid until `lease + 900s` by default. ### Create ```http POST /v1/sessions Content-Type: application/json PAYMENT-SIGNATURE: # omitted on the first attempt ``` An unpaid request returns `402` with a base64 `PAYMENT-REQUIRED` header containing the price. Sign it and retry with `PAYMENT-SIGNATURE`. A retry with the same payment returns the same session and capability, not a second charge. Request body (tiers: `short`, `standard`, `extended`, `long`, `custom`): ```json { "tier": "standard", "clientPublicKey": "", "clientNonce": "" } ``` Custom tiers additionally require `durationSeconds`, `cpuMillis`, `memoryMiB` and `diskMiB`. Do not send checkpoint fields (`idlePolicy`, `maxLifetimeSeconds`): the hosted beta does not offer suspended sessions. The response carries `sessionId`, `capability`, `state`, `limits`, `capabilityExpiresAt` and payment details. `201` is a new session, `200` is an idempotent replay. ### Status, run, destroy ```http GET /v1/sessions/{id} POST /v1/sessions/{id}/operations GET /v1/sessions/{id}/operations?request=&requestId= GET /v1/sessions/{id}/requests/{requestId}?waitMs=20000 DELETE /v1/sessions/{id} ``` `POST /operations` takes `{ requestId, envelope, timeoutMs?, waitMs? }`. The `requestId` is an 8 to 128 character idempotency key. Reusing it returns the same result and does not execute twice. One foreground operation per session; a second gets `409 busy`. The envelope is a sealed box. The API never sees the operation type, command, environment or output. Ops include `exec`, `file.put`, `file.get`, `file.list`, `file.stat`, `service.start`, `service.list`, `service.stop`, `http.request`, HTTP streams and WebSockets. Use the SDK or CLI. `202` means still running; poll the request. `409 outcome_unknown` is terminal and means the controller restarted with the request in flight: the command may have run. Do not blindly retry with a new id if the command is not idempotent. ### No suspend, no resume A session ends when its lease ends or you destroy it. There is no suspend, no resume and no checkpoint endpoint on the hosted beta: `POST /v1/sessions/{id}/suspend` exists in the open-source build, where the workspace is a plaintext PVC, and the hosted service does not sell that. If you need work to survive, download it before the lease ends. ## Limits | Limit | Value | | --- | --- | | Tiers | `short` 60 s / 0.5 vCPU / 512 MiB / 256 MiB | | | `standard` 300 s / 1 vCPU / 1 GiB / 1 GiB | | | `extended` 900 s / 2 vCPU / 2 GiB / 2 GiB | | | `long` 1800 s / 2 vCPU / 4 GiB / 4 GiB | | Lease | 1800 s maximum on the hosted deployment; 3600 s is the protocol ceiling and no deployment may exceed it | | Custom ceiling | 2 vCPU / 4 GiB / 8 GiB | | Workspace | `/workspace`, paths confined to it, destroyed with the lease | | File or archive | 8 MiB per payload | | Command output | 256 KiB per stream, then truncated | | Command time | 300 s, `min(requested, remaining lease, maxCommandSeconds)` | | Result wait | `waitMs` up to 90 000 ms, then `202 pending` | | Listing | 5000 entries | | Concurrency | one active foreground operation per session; background processes are killed when the command returns | | Processes | pod `pids.max` 1024; `maxProcesses` is advisory | | Networking | no inbound; egress only through the egress proxy, to destinations on 443, so the guest cannot reach the cluster network or the metadata service | Prices are configuration (`SESSION_TIERS`), not economics. Read `GET /v1/pricing` on the API you are calling for the live table; never hardcode a price in a client. The 90 s `waitMs` cap is deliberate: a longer request is killed by the edge proxy at 100 s, so the client never sees the `202` it needs to poll. ## Error codes | HTTP | code | meaning | | --- | --- | --- | | 400 | `invalid_request`, `tier_duration_mismatch`, `invalid_duration`, `plaintext_not_accepted` | bad input | | 401 | `capability_required` | missing capability | | 402 | `payment_required`, `payment_invalid:*`, `payment_settlement_rejected:*` | payment problem | | 404 | `session_not_found` | wrong capability or unknown session | | 409 | `payment_in_progress`, `spec_mismatch`, `busy`, `outcome_unknown`, `session_not_usable` | conflict | | 410 | `lease_expired`, `capability_expired`, `result_expired` | gone | | 413 | `payload_too_large` | envelope too big | | 429 | `rate_limited` (`scope: payer` or `ip`) | honour `Retry-After` | | 429 | `creates_disabled` | the operator has switched new sessions off. Stop, do not retry a payment | | 503 | `control_plane_unavailable`, `provisioning_unavailable` | transient | Command-level errors (`ok: false`) include `path_outside_workspace`, `quota_exceeded`, `file_too_large`, `unsafe_archive`, `not_found`, `invalid_cwd`, `spawn_failed`, `service_not_found`, `port_in_use`, `service_not_listening`. ## Rules for agents - Always destroy a session in a `finally` block, even if the command failed. - Collect output files before the lease expires. Nothing survives termination. - Do not put secrets inline in command strings. Pass them with `--env` or the SDK's env field, and remember they are inside the sealed envelope but still visible to the guest process. - Keep payloads under 8 MiB. Chunk or split larger inputs. - Use `--json` or the SDK's typed results. Do not scrape human output. - Do not retry a non-idempotent command with a new `requestId` after `outcome_unknown`. - On `402`, pay once and retry with the same payment. On `429`, back off. On `429 creates_disabled`, stop until the operator says otherwise. - Use the warm-pool path through the API; do not try to talk to a guest directly. There is no inbound networking. - For an HTTP service, start it with `service.start` and call it with the relay `http.request` operation. Do not expect a routable port. ## Security scope The transport is sealed client-side to the guest's ephemeral key: the API, controller, relay, database and payment layer route ciphertext and hold no decryption key. Isolation between sandboxes is a Kata microVM, and the boundary properties the suite tests were verified at control `0.1.33` and guest `0.1.33`: separate guest kernel, no reach to a peer session, the Kubernetes API, a node, the metadata endpoint or a Service VIP, no host mounts and no service-account token in the guest, and the internet only through the proxy. That is not a hardware root of trust and no escape was attempted. The development attestation key ships in the repository, so anyone can produce the binding: the client learns which key it is talking to, not what the operator is running. Checkpoint storage is plaintext, which is why suspend is not offered. Do not describe this system as confidential computing, attested, provider-blind or isolated. ## Hosted beta: rules, refunds, data - **Acceptable use.** Run work you have the right to do. Not allowed: attacking or scanning systems you do not own, spam, crypto mining, illegal content, escaping the sandbox, or reaching another session, the cluster network or its metadata service. Report abuse to . - **Payment.** Real USDC on Base (`eip155:8453`), one charge per session, settled through the Coinbase CDP facilitator. No accounts and no stored balance. Free access is by invitation only. - **Refunds.** Full refund to the paying wallet if a session never reaches READY, or if the service ends it because the relay could not recover (`failure:relay_lost`). No refund for a session the client destroys, or for one that simply expires after READY. Refunds are queued in the payment ledger and sent by a separate worker, so they are not instant; a refund that cannot be sent automatically stays queued for an operator. - **Data.** Session metadata (tier, limits, timings, state), the paying wallet address and the payment ledger are recorded. Commands, file contents and output are ciphertext to the API, controller and relay. The guest sees what it runs, and nothing you write survives the lease. - **No SLA.** One operator, one region, one control-plane node, one Postgres primary. A control-plane node loss is an outage until it comes back, and no failover has been measured. - **No suspend.** There is no checkpoint, no resume and no place to park a workspace. Finish and download within the lease. ## Local verification ```bash make up # kind + Cilium + images + deploy (~2 min) make demo-session # pay, create, exec, upload, download, destroy make down npm ci make verify # typecheck, structure lint, unit + property tests make test # adds integration against the real guest binary ``` Local clusters use `runc`, not microVMs, but exercise the same API, relay and guest. Prerequisites: Docker, `kind`, `kubectl`, Cilium CLI, Node >= 24, Go >= 1.26. ## Optional - [Roadmap](https://github.com/ejackson-vp/sandbox/blob/main/ROADMAP.md): what comes next. - [Changelog](https://github.com/ejackson-vp/sandbox/blob/main/CHANGELOG.md): release history. - [Benchmarks](https://github.com/ejackson-vp/sandbox-bench): the measurement harness. - [ADRs](https://github.com/ejackson-vp/sandbox/tree/main/docs/adr): why the load-bearing choices were made. - [HTML overview](https://github.com/ejackson-vp/sandbox/tree/main/site): this page, for humans.