---
name: collimate
description: >-
  Use Collimate to run code in fast, hardware-isolated microVM sandboxes and to
  LIVE-FORK a running sandbox into many copies that keep its live process memory.
  Reach for this whenever you need to (a) run untrusted or generated code safely,
  (b) prepare an environment once and branch it to try several actions in
  parallel, or (c) drive RL/agentic rollouts. Keywords: sandbox, microVM,
  Firecracker, fork, live fork, best-of-N, tree search, isolated exec, Collimate.
---

# Collimate

Collimate gives you fast, hardware-isolated microVM sandboxes over a small REST
API and a hosted MCP endpoint. Every sandbox is a real VM (KVM/Firecracker), not
a shared-kernel container, so it is safe for untrusted and model-generated code.

The one idea to internalize: **prepare once, fork many.** Instead of booting a
fresh environment and replaying its history for every branch, drive one sandbox
to a useful state, then **live-fork** it into N children that each keep the
parent's live process memory (installed packages, loaded models, warmed caches).
Forking a running sandbox costs milliseconds and removes the "replay tax."

## Connect

- REST base URL: `https://api.collimate.ai`
- Hosted MCP endpoint: `https://mcp.collimate.ai` (streamable HTTP)
- Auth: `Authorization: Bearer $COLLIMATE_API_KEY` where the key is
  `col_<tier>_<id>_<secret>`. The same key works for REST and MCP.

If MCP is available, prefer the tools `sandbox_create`, `sandbox_exec`,
`sandbox_write_file`, `sandbox_fork`, `sandbox_suspend`, `sandbox_resume`,
`sandbox_list`, `sandbox_delete`. Otherwise use REST as below.

## Core workflow (REST)

1. Create a sandbox from a template (`python` on the managed cloud, or one your
   tenant owns / any OCI image when self-hosted):

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

2. Run work in it (stage files first, then run a command). Execs are serialized
   per sandbox; files and processes persist:

   ```bash
   curl https://api.collimate.ai/v1/sandboxes/sbx_.../exec \
     -H "Authorization: Bearer $COLLIMATE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "files": [{"path":"m.py","content":"print(42)"}],
           "command": "python3 m.py", "timeout_seconds": 30 }'
   # -> { "stdout": "42\n", "exit_code": 0, "seed": "...", "seed_ack": "verified" }
   ```

   Exec fields: `command` (shell string) OR `code` (via the template interpreter)
   OR `commands` (argv arrays); `files` (staged first); `timeout_seconds` (<=3600);
   `seed` (64 hex chars — pin for reproducibility); `egress` (per-exec network
   policy).

3. **Live-fork** the prepared sandbox to branch:

   ```bash
   curl https://api.collimate.ai/v1/sandboxes/sbx_.../fork \
     -H "Authorization: Bearer $COLLIMATE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "count": 8 }'
   # -> { "parent": "sbx_...", "children": [ { "id": "sbx_a" }, ... ] }
   ```

   Each child is an independent microVM that resumes from the parent's live
   memory. The parent keeps running. Take a different action in each child; keep
   the best. Fork the promising children again to go deeper.

4. Suspend to pause the meter without losing state, resume in place, or delete:

   ```bash
   curl -X POST   https://api.collimate.ai/v1/sandboxes/sbx_.../suspend  -H "Authorization: Bearer $COLLIMATE_API_KEY"
   curl -X POST   https://api.collimate.ai/v1/sandboxes/sbx_.../resume   -H "Authorization: Bearer $COLLIMATE_API_KEY"
   curl -X DELETE https://api.collimate.ai/v1/sandboxes/sbx_...          -H "Authorization: Bearer $COLLIMATE_API_KEY"
   ```

## Python SDK (for RL / rollouts)

```bash
pip install collimate-rl
```

```python
from collimate_rl import Sandbox, connect

client = connect()                                     # reads COLLIMATE_API_KEY
with Sandbox("python", client=client) as sb:           # forks a warm clone
    sb.upload_bytes("/work/task.py", source)           # byte-exact file in
    r = sb.exec(command="cd /work && python task.py", timeout_seconds=120)
    if r.ok:
        out = sb.download("/work/out.json")            # byte-exact file out
```

## Rules of thumb

- To branch (best-of-N, tree search, "try a few things"): FORK the prepared
  sandbox. Do not create N fresh sandboxes and replay setup in each.
- Fork only a settled sandbox (no in-flight exec) — a fork during an exec returns
  `409 busy`.
- Suspend a sandbox you're waiting on; it stops billing and keeps exact state.
- Branch on the error `code` (stable), not the message. `429 quota_exceeded` =
  at your concurrency cap (suspend/delete one); `429 rate_limited` = back off and
  honor `Retry-After`; `401 unauthorized` = key problem.
- For reproducible runs, pass a `seed` and check `seed_ack == "verified"`.
- Never print a large artifact; write it to a file and download it (exec output
  is capped ~16 MiB).

## Learn more

- Live fork: https://docs.collimate.ai/core/live-fork/
- API reference: https://docs.collimate.ai/reference/api/
- MCP quickstart: https://docs.collimate.ai/start/mcp/