Quickstart

Get an API key

Request access to the managed API and you'll receive a key that looks like col_live_…. Keys are sent as a bearer token and rate-limited per key. Need Collimate in your own cloud? It is a proprietary, managed service, with bring-your-own-cloud (BYOC) deployment available.

Install the SDK

Both SDKs are zero-dependency: no requests, no heavy client. Pick your language:

pip install collimate

npm install @collimate/sdk

Run code in a VM

Each call spawns a fresh, isolated VM from a template (pass the template_id you want to spawn from, e.g. python), runs your code, and returns the output plus timings. The VM is torn down when the call ends.

from collimate import Sandbox

sb = Sandbox("col_live_your_key")
r = sb.run("print(sum(range(100)))", "python")

print(r.stdout)         # 4950
print(r.exit_code)      # 0
print(r.fork_time_ms)   # 0.7
print(r.total_time_ms)  # 8.0

import { Sandbox } from "@collimate/sdk";

const sb = new Sandbox("col_live_your_key");
const r = await sb.run("print(sum(range(100)))", "python");

console.log(r.stdout);        // 4950
console.log(r.exit_code);     // 0
console.log(r.fork_time_ms);  // 0.7

curl -X POST https://api.collimate.ai/v1/exec \
  -H 'Authorization: Bearer col_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"code":"print(sum(range(100)))","template_id":"python"}'

Fan out a batch

The rollout phase is embarrassingly parallel. Submit many snippets at once and each runs in its own VM, concurrently. This is ideal for sampling a group of completions (GRPO-style) from the same starting environment.

results = sb.run_batch(
    [f"print({i} ** 2)" for i in range(64)],  # 64 parallel VMs
    "python",
)
for r in results:
    print(r.stdout.strip(), r.fork_time_ms)

const results = await sb.runBatch(
  Array.from({ length: 64 }, (_, i) => `print(${i} ** 2)`),
  "python",
);
results.forEach((r) => console.log(r.stdout.trim(), r.fork_time_ms));

Hold a session for a step loop

A throwaway VM is stateless. For an environment your agent drives over many steps (search, edit, test, repeat), open a session: one live VM held alive, with filesystem state persisting between calls. This is the shape an RL environment's step() loop needs.

# Open a session spawned from your environment
SID=$(curl -s -X POST https://api.collimate.ai/v1/sessions \
  -H 'Authorization: Bearer col_live_...' \
  -d '{"template_id":"my-env"}' | jq -r .session_id)

# Step through it; state carries over between calls
curl -X POST https://api.collimate.ai/v1/sessions/$SID/exec \
  -d '{"commands":[["grep","-rn","TODO","src/"]]}'

curl -X POST https://api.collimate.ai/v1/sessions/$SID/exec \
  -d '{"files":[{"path":"/app/patch.py","content":"# ...edited..."}]}'

curl -X POST https://api.collimate.ai/v1/sessions/$SID/exec \
  -d '{"commands":[["python","-m","pytest","-x"]]}'

# Done: reclaim the VM
curl -X DELETE https://api.collimate.ai/v1/sessions/$SID

Want to explore several actions from the same point? Branch the live session instead of replaying it.