sandboxes

Create & exec

Room → from-template → exec. Prefer MCP.

Must-check first

1. health — topology + pool readiness

2. usage — credits, entitlement, quotas

3. Stop on 402 risk / empty credits / not entitled → send the user to Billing

MCP sequence

1. room_create — unique room_id

2. sandbox_create — agent_id, unique guest_cid (9100–9999), memory_mib, optional template_id

3. sandbox_exec — e.g. ["echo", "hello"]

4. Leave running unless the user asks to destroy

REST

ROOM=room-hello-$RANDOM
curl -fsS -X POST "$FYSTASH_API/v1/rooms" \
  -H "Authorization: Bearer $FYSTASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"room_id\":\"$ROOM\"}"

curl -fsS -X POST "$FYSTASH_API/v1/rooms/$ROOM/sandboxes/from-template" \
  -H "Authorization: Bearer $FYSTASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"a1","guest_cid":9100,"memory_mib":256}'

curl -fsS -X POST "$FYSTASH_API/v1/rooms/$ROOM/sandboxes/a1/exec" \
  -H "Authorization: Bearer $FYSTASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"argv":["echo","hello"]}'

Create performance

Creates use a warm pool when available. Create wall-clock and resume are different metrics — see Standby & resume. Production is topology=nested.

Pool miss

HTTP 503 means the warm pool could not satisfy the request. Retry shortly; do not invent a cold-prepare workaround from the client.