Sandbox Quickstart

Create one sandbox on a provisioned deployment, verify command output, and confirm teardown.

Run one command in an isolated runtime, keep its execution result, and stop the runtime when finished. This walkthrough uses the controller’s HTTP contract directly.

A provisioned deployment is required. Check the dated host report and obtain your workspace URL and API key before starting. A published reference does not establish that the hosted service is available or that your workspace has runtime capacity.

Prerequisites

Use Bash, curl 7.76+, and jq. Obtain an API key with permission to create, inspect, execute in, and stop a sandbox. Confirm the deployment’s supported isolation modes and resource limits. This example requests a Linux container for five minutes; runtime and quota policies can reject the request.

Set these in the same terminal, replacing the deployment URL with the one supplied to you:

export SANDBOX_URL="https://YOUR-PROVISIONED-HOST/api/v1"
export STATESET_SANDBOX_API_KEY="YOUR_SANDBOX_API_KEY"
export SANDBOX_CREATE_KEY="YOUR_UNIQUE_PERSISTED_SMOKE_REQUEST_KEY"

API keys use Authorization: ApiKey. The controller also accepts Bearer for a JWT; putting an API key after Bearer does not turn it into a JWT. The source-backed correction is recorded in this repository’s Sandbox overlay. Registration returns no usable API key before email verification. Preserve the create key with the exact body before the first request; reuse it only for that original operation, never a different test run. Use a unique 1–200 character ASCII key without spaces, leaving room for the execution-key suffix below.

Create, execute, and stop

Save this as sandbox-smoke.sh. It captures the returned ID, polls with a finite budget, verifies the command result, and attempts cleanup on exit once an ID is known.

#!/usr/bin/env bash
set -euo pipefail
: "${SANDBOX_URL:?Set the provisioned base URL including /api/v1}"
: "${STATESET_SANDBOX_API_KEY:?Set the sandbox API key}"
: "${SANDBOX_CREATE_KEY:?Set and persist a unique key for this original create request}"
SANDBOX_URL="${SANDBOX_URL%/}"
printf '%s\n' "$SANDBOX_CREATE_KEY" > sandbox-create-key.txt

request() {
  curl --silent --show-error --fail-with-body --max-time 30 \
    --header "Authorization: ApiKey $STATESET_SANDBOX_API_KEY" "$@"
}

SANDBOX_ID=""
cleanup() {
  if [ -n "$SANDBOX_ID" ]; then
    if ! request --request POST "$SANDBOX_URL/sandbox/$SANDBOX_ID/stop" > sandbox-stop.json \
      || ! jq -e '.success == true' sandbox-stop.json > /dev/null; then
      printf 'Cleanup failed. Inspect sandbox %s and stop it manually.\n' "$SANDBOX_ID" >&2
      return 1
    fi
    printf 'Stop request accepted for %s; verify teardown below.\n' "$SANDBOX_ID"
  fi
}
trap cleanup EXIT

request --request POST "$SANDBOX_URL/sandbox/create" \
  --max-time 210 \
  --header "Idempotency-Key: $SANDBOX_CREATE_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"desktop_os":"linux","cpus":"1","memory":"1Gi","isolation":"container","timeout_seconds":300}' \
  > sandbox-created.json
SANDBOX_ID=$(jq -er '.sandbox_id | select(type == "string" and length > 0)' sandbox-created.json)
printf '%s\n' "$SANDBOX_ID" > sandbox-id.txt

ready=false
for attempt in {1..30}; do
  request "$SANDBOX_URL/sandbox/$SANDBOX_ID/status" > sandbox-status.json
  status=$(jq -er '.status' sandbox-status.json)
  case "$status" in
    running) ready=true; break ;;
    creating) sleep 2 ;;
    *) printf 'Unexpected sandbox state: %s\n' "$status" >&2; exit 1 ;;
  esac
done
if [ "$ready" != true ]; then
  printf 'Sandbox did not become ready within 30 observations.\n' >&2
  exit 1
fi

request --request POST "$SANDBOX_URL/sandbox/$SANDBOX_ID/execute" \
  --header "Idempotency-Key: ${SANDBOX_CREATE_KEY}-exec" \
  --header 'Content-Type: application/json' \
  --data '{"command":["printf","sandbox-ok"],"working_dir":"/workspace","timeout":10000}' \
  > sandbox-execution.json
jq -e '.exit_code == 0 and .stdout == "sandbox-ok" and (.outcome // "known") != "unknown" and (.system_error // "") != "exec_stream_lost"' sandbox-execution.json
printf 'Command output verified for sandbox %s\n' "$SANDBOX_ID"

bash sandbox-smoke.sh

Success: the script prints a real sandbox ID, observes running, verifies exit code 0 and output sandbox-ok, and receives a successful stop response. It saves the responses locally for inspection. These are observed criteria, not guarantees of provisioning speed.

The create request has a separate 210-second client wait; the sandbox’s 300-second lifetime still includes startup. Neither the example nor a warm success establishes cold-start capacity. If create times out before returning an ID, preserve the saved key/body and inspect the original request and workspace list. Recover through the compatible idempotency contract before choosing another operation. The trap cannot stop an identity it never received.

A 200 execute response can retain an unknown outcome; it is not permission to rerun the command. Use original receipt recovery for lost streams, record_pending, or unconfirmed result storage. This script contacts no other service and does not automatically retry mutations.

Verify teardown

After the script exits, read the status with the saved ID:

SANDBOX_ID=$(cat sandbox-id.txt)
curl --silent --show-error --max-time 30 \
  --write-out '\nHTTP %{http_code}\n' \
  --header "Authorization: ApiKey $STATESET_SANDBOX_API_KEY" \
  "$SANDBOX_URL/sandbox/$SANDBOX_ID/status"

A terminal terminated state or 404 with the same workspace credentials shows API retirement at that identity; physical pod/resource cleanup and billing reconciliation need their own observations. terminating is still in progress; recheck within your operational deadline. A 401, 403, network error, or 5xx does not prove teardown. Confirm with the workspace operator if the result remains uncertain.

Troubleshooting

Failure	Next action
401	Check the service-specific key and ApiKey prefix
403	Check scope, organization membership, and sandbox permissions
Creation rejected	Read field errors and confirm supported resources and isolation mode
429	Inspect quota and existing runtimes before creating another
Readiness budget exhausted	Inspect the saved status and provisioning logs
Command returns nonzero	Read sandbox-execution.json; do not treat HTTP success as command success
Stop fails	Use sandbox-id.txt to inspect and stop the same runtime; retain the error

Next steps

• Files and longer tasks — extend the verified runtime workflow.
• Sandbox API — schemas, lifetime, execution, and files.
• Sandbox MCP — connect an agent to its runtime tools.
• Support — share the failed step and redacted result.