Sandboxes

POST /v1/sandboxes runs a JavaScript program in QuickJS compiled to WebAssembly. It uses the same key, balance and caps as your chat calls, and each run returns a signed receipt.

curl -i https://YOUR-PROVN-HOST/v1/sandboxes \
  -H "Authorization: Bearer $PROVN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "let s = 0; for (let i = 0; i < 10; i++) s += i; console.log(s); s",
    "timeout_ms": 2000
  }'

HTTP/1.1 200 OK
x-provn-request-id: req_...
x-provn-cost-micro-usd: 1
x-provn-receipt: eyJ...
x-provn-receipt-sig: 0x...
x-provn-receipt-signer: 0x...

{
  "status": "ok",
  "stdout": "45\n",
  "result": 45,
  "error": null,
  "cpu_ms": 4,
  "truncated": false,
  "receipt": {
    "id": "req_...",
    "receipt": "eyJ...",
    "signature": "0x...",
    "signer": "0x...",
    "payload": { "v": 1, "kind": "sandbox", "units": { "cpu_ms": 4, "mem_limit_mb": 32 } }
  }
}

Cost

Provn meters each run by CPU millisecond at 50 micro-USD per CPU second, with a 1 micro-USD minimum. A run that uses 120 ms of CPU costs 6 micro-USD. The 4 ms run above falls under the minimum and costs 1.

Receipt

Sandbox receipts use kind: "sandbox", and units holds cpu_ms and mem_limit_mb in place of token counts. The fingerprint is the first 16 hex characters of SHA-256 over the code you sent. A run that fails still gets a receipt, with status set to error or timeout and an error_class field.

Limits

• timeout_ms defaults to 3000 and tops out at 5000.
• Memory is capped at 32 MB, code at 64 KB and captured output at 32 KB (truncated turns true past that).
• JavaScript only, in QuickJS. Node.js modules, browser APIs, network and filesystem are absent.
• Send x-provn-run to chain the run's receipt into a run, the same as chat calls.
• A key's cap, allowlist, expiry and rate limit apply to sandbox calls as they do to chat.
• Provn stores the code's fingerprint and never the code.