# sandboxrouter: sign-up for agents

sandboxrouter starts isolated Linux sandboxes for running code, on whichever provider (E2B, Daytona, Maritime, ...) is cheapest and working, behind one API key. You can open an account yourself, with no browser. A person pays and can claim the account later.

Base URL: https://api.sandboxrouter.ai

## 1. Open an account

```http
POST https://api.sandboxrouter.ai/v1/signup
Content-Type: application/json

{"email": "your-person@example.com"}
```

`email` is optional: it's where receipts and abuse notices go. The answer (201):

```json
{
  "apiKey": "sr_live_...",
  "account": "agent-ab12cd",
  "balanceUsd": 0,
  "claimUrl": "https://api.sandboxrouter.ai/claim?token=src_..."
}
```

Store `apiKey` now; it is shown only once. Send it on every call as `Authorization: Bearer <apiKey>`. One address may open 10 accounts an hour.

## 2. Get credit

New accounts have no credit, and sandboxes won't start without it. Ask for a payment link and give it to your person:

```http
POST https://api.sandboxrouter.ai/v1/billing/checkout
Authorization: Bearer <apiKey>
Content-Type: application/json

{"usd": 10}
```

`usd` is 5, 10, 25, 50 or 100. The answer has `url`, a card checkout page. The credit appears within a minute of payment. Check it with:

```http
GET https://api.sandboxrouter.ai/v1/account
Authorization: Bearer <apiKey>
```

## 3. Run code

```http
POST https://api.sandboxrouter.ai/v1/sandboxes            {"vcpu": 2, "memoryGb": 4, "timeoutMinutes": 30}
POST https://api.sandboxrouter.ai/v1/sandboxes/<id>/exec  {"cmd": "python3 -c 'print(6*7)'"}
PUT  https://api.sandboxrouter.ai/v1/sandboxes/<id>/files?path=/tmp/a.txt   (raw body)
GET  https://api.sandboxrouter.ai/v1/sandboxes/<id>/files?path=/tmp/a.txt
DELETE https://api.sandboxrouter.ai/v1/sandboxes/<id>
GET  https://api.sandboxrouter.ai/v1/sandboxes            your sandboxes, running first, with what each costs
```

The create answer:

```json
{
  "id": "agent37:uw453so911",
  "provider": "agent37",
  "size": {"vcpu": 2, "memoryGb": 4},
  "hourlyUsd": 0.006858,
  "expiresAt": "2026-11-12T10:30:00.000Z",
  "attempts": [{"provider": "agent37", "ok": true, "ms": 790}]
}
```

To retry a create safely (after a timeout, say), send a header `Idempotency-Key: <any unique string>` with it. The same key returns the same sandbox for 24 hours instead of starting, and charging for, another. Use a new key for each sandbox you mean to start.

`hourlyUsd` is what you're charged per hour. `timeoutMinutes` is how long the sandbox may live: default 30, at most 240. It's killed and billing stops then, so kill it sooner when you're done. Leave out `vcpu` and `memoryGb` for 2 vCPU / 4 GB (1 to 8 vCPU, 1 to 16 GB). Unknown fields are refused rather than ignored.

Add `"stream": true` to exec for server-sent events (`stdout`, `stderr`, then `result`). From TypeScript: `new Client({ baseUrl: "https://api.sandboxrouter.ai", apiKey })` from `@sandboxrouter/sdk`.

Pricing: what the provider charges for the size, plus 5.5%, billed by the second while the sandbox runs. That's its list price, or more where we've measured that a provider bills more than its list. Each running sandbox needs $0.10 of credit to start. Limits: 5 at once, 8 vCPU / 16 GB. When credit runs out, running sandboxes are stopped. No GPUs yet.

## 4. Let your person claim the account

Give your person `claimUrl`. They sign in and confirm, and the account, its keys, credit and sandboxes move to their dashboard at https://api.sandboxrouter.ai/dashboard. Your key keeps working and now spends their credit. A claim link works once.

## Errors

Errors are JSON: `{"error": "...", "code": "...", "attempts": [...]}`. `code` is set when routing failed.

| Status | `code` | Meaning |
|---|---|---|
| 400 | `bad_request` | a field is wrong or unknown; `error` says which |
| 401 | | missing, wrong or revoked key |
| 402 | | not enough credit: get a payment link (step 2) |
| 403 | | account blocked; your person should contact support |
| 422 | `no_provider` | no provider can take this size |
| 429 | | too many sandboxes at once, or too many sign-ups |
| 502 | `setup` | a provider refused the request; not worth retrying as is |
| 503 | `all_failed` | every provider that fits was down or busy; `attempts` says why. Retry in a minute |
| 504 | `timeout` | starting took too long; retry |

Mining, scanning, proxies and attacks on other systems get the account blocked. Full rules: https://api.sandboxrouter.ai/acceptable-use and https://api.sandboxrouter.ai/terms.