Sandboxes

Sandboxes run short Python or Node.js programs in disposable, network-disabled containers on a dedicated sandbox node. Code never executes in the web or gateway process. Each execution is reserved, billed per second and receipted like an inference request.

Endpoint

Requires an API key with the sandboxes scope. The call is synchronous: it returns when the program exits or times out.

Request body

Programs receive no stdin and cannot open network connections.

Example

curl https://www.hushcompute.xyz/v1/sandbox/executions \
  -H "Authorization: Bearer $HUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "runtime": "python",
    "timeout_seconds": 10,
    "code": "import statistics\nprint(statistics.mean([3, 5, 8, 13]))"
  }'

Response

{
  "id": "sbxr_01K58ZY3D5F7H9K2M4P6R8T1V3",
  "object": "sandbox.execution",
  "status": "completed",
  "exit_code": 0,
  "stdout": "7.25\n",
  "stderr": "",
  "stdout_truncated": false,
  "stderr_truncated": false,
  "duration_ms": 412,
  "runner": "docker",
  "receipt": {
    "id": "rcpt_01K58ZY3E8G1J3L5N7Q9S2U4W6",
    "hash": "0x1c7e…9d20",
    "signature": "0x44ab…f31c",
    "signer": "0x3A4c…91De",
    "url": "https://www.hushcompute.xyz/proofs/rcpt_01K58ZY3E8G1J3L5N7Q9S2U4W6"
  },
  "billing": {
    "cost_micro_usd": "40",
    "cost_usd": "0.00004",
    "fingerprint_salt": "0x8e30…b6a1"
  }
}

A non-zero exit code is not an API error: the response is HTTP 200 and the execution is billed and receipted.

Limits

Isolation

Separate execution node

The gateway sends each execution to a sandbox node over an authenticated internal protocol. Requests are signed with HMAC-SHA256 over the method, path, timestamp and body hash; the node rejects timestamps more than 60 seconds off and replayed execution IDs. Responses are signed too, and the gateway verifies the signature before a result is billed or committed to a receipt.

Per-execution container

• A fresh container for every execution, removed afterwards. Nothing persists between executions.
• No network (the container has no network interface).
• Read-only root filesystem; only the in-memory workspace and /tmp are writable, and neither allows executing binaries.
• Runs as an unprivileged, non-root user with all Linux capabilities dropped and privilege escalation disabled.
• cgroup limits on memory (without swap), CPU and process count; file size, open file and core dump limits.
• Code is passed to a fixed launcher over stdin, never through command-line arguments. Runtime images are pinned locally and never pulled at execution time.
• Container logging is disabled, so program output is not persisted by the container runtime.

Pricing

Executions are billed per started second of wall-clock time, with a minimum of 1 second:

These are the default rates; operators can set a different per-second base price. Before execution the gateway reserves the cost of the full timeout, and it releases the unused part when the program finishes.

Statuses and receipts

Receipts for executions have operation: "sandbox.execute", model: null, the runtime, zero token counts and latency_ms equal to the execution duration. The input fingerprint commits to {"code":…,"runtime":…} and the output fingerprint to {"exit_code":…,"stderr":…,"stdout":…} as returned. See Receipts.

Errors

When the node cannot run the code (sandbox_error, service_unavailable), the reservation is released and no receipt is issued.

Local development

The runner field states how an execution was handled. Production deployments use docker. Two development-only modes exist:

• dev-process: runs code as a plain host process with no isolation. The sandbox node refuses this runner in production.
• mock: used when no sandbox node is configured on a development deployment. Code is not executed; stdout says so.

Availability