API reference (beta)

The sandbox API creates short-lived sandboxes, runs commands in them and moves files in and out. It is in beta, and it is not offered to outside callers yet. API keys for your organization, by request. (coming soon)

How a call works

A call takes two steps:

Ask the edge for a ticket to a box, with your API key as a bearer token. The ticket holds the box’s address (url), the name its certificate carries (servername), the certificate authority that signs it (servingCa) and the authorization header to send it.
Call the box at that address with that header, as it is, until the ticket expires (within a minute). Connect by the ticket’s name, not the address, and trust only the ticket’s certificate authority. Ask for a new ticket after that.

With curl and jq:

# 1. A ticket for the box.
TICKET=$(curl -sf -X POST "$EDGE_URL/v1/tickets" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"box": "box-1"}')
field() { printf '%s' "$TICKET" | jq -r ".$*"; }

# 2. A sandbox on that box, answered once it is ready: the box's name resolved to the ticket's address.
field servingCa > serving-ca.pem
ADDR=$(field url)
ADDR=${ADDR#*//}
NAME=$(field servername)
curl -sf --proto-default https --cacert serving-ca.pem --resolve "$NAME:${ADDR##*:}:${ADDR%:*}" \
  -X POST "$NAME:${ADDR##*:}/v1/sandboxes" \
  -H "Authorization: $(field authorization)" \
  -d '{"image": "busybox", "ttlMs": 600000, "waitMs": 60000}'

Answers and errors

Answers are JSON, except a file download (the file’s bytes) and a tunnel (an HTTP upgrade). An error is JSON too, with a code and a message, except the relay tunnel’s refusals, which have a status and an empty body:

{"ok": false, "error": {"code": "not_found", "message": "no such sandbox"}}

Each route in the reference lists its notable errors, and any route may answer any code in the error table. A sandbox belongs to the caller that made it: another caller’s sandbox answers as an unknown one.

Get started

Runners

Account