Skip to content
Sandworld

Quickstart

Sandworld environments are deterministic twins of real app categories. An agent acts only through typed tools; when it's done, the task's verifier checks the final state and tells you exactly which checks passed. Three calls cover the whole loop.

1. Start an episode

curl -s -X POST https://sandworld.dev/api/v1/environments/quickbasket/episodes \
  -H "content-type: application/json" \
  -d '{"task_id": "qb-01", "seed": 7, "agent_name": "my-agent"}'

The response has the episode_id, the user's instruction, the app's policy and the tools with JSON schemas. Give all three to your agent.

2. Call tools

curl -s -X POST https://sandworld.dev/api/v1/episodes/$EPISODE_ID/step \
  -H "content-type: application/json" \
  -d '{"tool": "list_delivery_slots", "arguments": {}}'

Each step returns the tool's observation — the same information a user of the app would see. Errors come back as data, the way a real API returns them.

3. Submit for verification

curl -s -X POST https://sandworld.dev/api/v1/episodes/$EPISODE_ID/submit

You get pass, a score and every check with detail. Use the checks as a reward signal, or open the episode in the workspace to replay it step by step.

From Python

The Python client (standard library only, in clients/python) wraps the same three calls and adds a Gymnasium-style wrapper:

from sandworld import SandworldEnv

env = SandworldEnv("quickbasket", task_id="qb-10")     # SANDWORLD_API_URL, SANDWORLD_API_KEY
obs, info = env.reset(seed=1)                          # info["tools"], info["policy"]
obs, reward, terminated, truncated, info = env.step(
    {"tool": "get_order", "arguments": {"order_id": "QB-10388"}}
)
obs, reward, terminated, truncated, info = env.step({"tool": "submit"})
print(reward, info["verification"].failed_checks)

examples/claude_agent.py runs Claude on any task end to end and prints each verifier check.

Next

  • API reference — authentication, every endpoint, training signals, fault injection, the local server.
  • Evaluate any model — Claude, OpenAI, Gemini, OpenRouter, vLLM or local models, with failure reasons.
  • Computer use — operate the twins through their screens and measure the GUI tax.
  • MCP server — let Claude Desktop, Claude Code or any MCP client drive the twins.
  • Harbor packages — export tasks as Harbor task directories for your own harness.
  • Environment spec — how twins, tasks, verifiers and QA probes are defined.