Sandboxes quickstart

This guide takes you from signup to a forked sandbox. The flow is four calls: list the catalog, create a sandbox from a catalog image, exec against it, fork it.

1. Get a key. Sign in to the console (Google or GitHub), then API keys → Create. A Demo key is free — no card:

   export COLLIMATE_API_KEY="col_demo_a1b2c3d4e5f60718_..."

2. Install the SDK (stdlib-only, zero dependencies):

   pip install collimate-rl

Note

The base URL for the managed API is https://api.collimate.ai. The sandboxes noun is the GA name; POST /v1/sessions remains a working alias for create, and the SDK keeps session-vocabulary code running everywhere.

1. Pick an image from the catalog

The catalog is the ready-to-run image library — every entry is already baked and ready to fork, so there is nothing to build or wait for. Pick an id:

REST

curl https://api.collimate.ai/v1/images \
  -H "Authorization: Bearer $COLLIMATE_API_KEY"
# { "templates": [ { "id": "python", "name": "python", "visibility": "public",
#                    "tier": "demo", "description": "Python 3, ready to run" } ] }

Python

from collimate_rl import connect

client = connect()          # reads COLLIMATE_API_KEY from the environment

for img in client.images():
    print(img["id"], "—", img.get("description", ""))
# python — Python 3, ready to run

Bringing your own image is the Pro upgrade — see the Pro quickstart.

2. Create a sandbox and run code

Create a sandbox from the catalog id, then exec against it. Files and processes persist between execs, so you reuse the same sandbox across steps.

1. Create a sandbox:

   REST

   curl https://api.collimate.ai/v1/sandboxes \
     -H "Authorization: Bearer $COLLIMATE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "template": "python" }'
   # { "id": "sbx_9f2a1c7b3e40", "template": "python", "state": "running", ... }

   Python

   sb = client.create_sandbox("python")
   print(sb["id"])   # sbx_9f2a1c7b3e40

2. Exec against it as many times as you like:

   REST

   curl https://api.collimate.ai/v1/sandboxes/sbx_9f2a1c7b3e40/exec \
     -H "Authorization: Bearer $COLLIMATE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "code": "print(sum(range(100)))" }'

   Python

   r = client.exec(sb["id"], code="print(sum(range(100)))")
   print(r["stdout"], r["exit_code"])   # "4950\n" 0

   You get back the captured output plus timing:

   {
     "id": "sbx_9f2a1c7b3e40",
     "stdout": "4950\n",
     "stderr": "",
     "exit_code": 0,
     "fork_time_ms": 0.0,
     "exec_time_ms": 11.8,
     "total_time_ms": 15.1,
     "seed": "3a7f…",
     "seed_ack": "verified"
   }

3. Delete it when you're done:

   REST

   curl -X DELETE https://api.collimate.ai/v1/sandboxes/sbx_9f2a1c7b3e40 \
     -H "Authorization: Bearer $COLLIMATE_API_KEY"

   Python

   client.delete_sandbox(sb["id"])

One-shot rollouts

For "fork, run once, discard", the SDK's rollout_once helper does the whole create → exec → delete round-trip in one call. See the RL quickstart.

3. Fork the running sandbox

The headline. Prepare a sandbox once, then fork it into N live children — each keeps the parent's process memory, so no reinstall and no replay.

REST

# Prepare state once, then fork the running sandbox 4 ways.
curl https://api.collimate.ai/v1/sandboxes/sbx_9f2a1c7b3e40/exec \
  -H "Authorization: Bearer $COLLIMATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "command": "pip install numpy" }'

curl https://api.collimate.ai/v1/sandboxes/sbx_9f2a1c7b3e40/fork \
  -H "Authorization: Bearer $COLLIMATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "count": 4 }'
# { "parent": "sbx_9f2a1c7b3e40", "children": [ { "id": "sbx_1a4f…" }, ... ] }
# each child already has numpy installed

Python

client.exec(sb["id"], command="pip install numpy")   # prepare state once

resp = client.fork(sb["id"], count=4)
children = [c["id"] for c in resp["children"]]
# each child already has numpy installed

The parent keeps running; each child is an independent microVM. This is the building block for tree search and best-of-N.

Next steps

• Live fork — the replay-tax argument and fork-tree search.
• MCP quickstart — drive sandboxes from Claude Code or Cursor.
• Pro quickstart — bring your own image and run GRPO-width rollouts.
• RL quickstart — rollout workloads with collimate-rl.
• API reference — every endpoint and field.