Get started

You need the gateway hostname and a credential. If you do not have a credential, whoever operates your deployment issues one — Provisioning.

export SANDBOX_GATEWAY_URL="https://sandbox.turing.com"   # or http://localhost:8780
export SANDBOX_API_KEY="…"

Local stack: Local development.

1. Confirm your credential and list agents

curl -sS -H "X-Api-Key: $SANDBOX_API_KEY" \
  "$SANDBOX_GATEWAY_URL/sandbox/v1/catalog?kind=agent"

You should see curated agents such as opencode, claude-code, codex, gemini-cli, oracle, terminus-2, and others. A 401 means the credential was not recognised.

Team token instead of API key:

curl -sS -H "Authorization: Bearer $TEAM_TOKEN" \
  "$SANDBOX_GATEWAY_URL/sandbox/v1/catalog?kind=agent"

Full table: Supported agents.

2. Run code (no agent, no job to poll)

curl -sS -H "X-Api-Key: $SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language":"python3.12","files":{"main.py":"print(sum(range(10)))"}}' \
  "$SANDBOX_GATEWAY_URL/sandbox/codeedit/v1/executions"

from sandbox_core.clients.sandbox_client import SandboxClient

client = SandboxClient.from_env()
print(
    client.run_code_execution(
        {"language": "python3.12", "files": {"main.py": "print(sum(range(10)))"}}
    )
)

Example response:

{"status":"ok","exit_code":0,"stdout":"45","stderr":"","duration_ms":5427,"truncated":false}

3. Run a catalog agent and poll

Use a real catalog agent_id. opencode is the recommended default.

JOB=$(curl -sS -H "X-Api-Key: $SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-correlation-id: my-first-run" \
  -d '{
    "agent_id": "opencode",
    "instruction": "list the files",
    "model": "anthropic/claude-sonnet-4-5"
  }' \
  "$SANDBOX_GATEWAY_URL/sandbox/agent/v1/runs" | jq -r .job_id)

curl -sS -H "X-Api-Key: $SANDBOX_API_KEY" \
  "$SANDBOX_GATEWAY_URL/sandbox/agent/v1/runs/$JOB"

Other catalog ids work the same way — swap agent_id for claude-code, codex, gemini-cli, openhands, cursor-cli, aider, or cline-cli (and send a matching model). Unknown ids → 400.

Live events:

curl -N -H "X-Api-Key: $SANDBOX_API_KEY" \
  "$SANDBOX_GATEWAY_URL/sandbox/agent/v1/runs/$JOB/events"

4. Run a benchmark task

You host a task archive over HTTPS; the platform fetches it.

curl -sS -H "X-Api-Key: $SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-correlation-id: my-first-benchmark" \
  -d '{
    "task_slug": "my-task",
    "metadata": {"task_archive_url": "https://storage.example/tasks/my-task.zip"},
    "agents": [{"name": "a", "harbor_agent": "oracle"}]
  }' \
  "$SANDBOX_GATEWAY_URL/sandbox/harbor/v2/jobs/execute-tasks"

task_archive_url must be inside metadata. For coding agents on Harbor, use harbor_agent: opencode, terminus-2, claude-code, etc. — see Supported agents.

When the job is terminal, gate on outcome.valid_for_scoring before trusting rewards. Walkthrough: Run a benchmark.

5. Optional — desktop or long-lived workspace

Goal	Profile	Guide
Same filesystem, many execs	`sandboxes-default` (pod)	Long-lived sandboxes
Linux GUI in browser	`desktop-ubuntu` (pod + noVNC)	Desktop sandboxes
Windows GUI	`desktop-windows` (EC2 VM + Guacamole)	same
macOS GUI	`desktop-macos` (external Mac cloud)	same

What to read next

Topic	Page
Components, pods, VMs	Architecture
Every agent id	Supported agents
Jobs and scoring	Core concepts
Credentials	Authentication
Errors and quotas	Errors and limits