Concepts

Collimate is a sandbox cloud with one engine and two front doors. This page is the mental model behind the rest of the docs.

The four nouns

Everything in Collimate reduces to four concepts, in one direction:

Image → bake → Artifact → Environment → Sandbox

Concept	What it is	Who owns it
Image	A container image (an OCI ref) — the input.	Yours. Demo picks one from the catalog; Pro brings its own.
Artifact	The ready state built from an image: booted, warmed, checkpointed — the thing sandboxes fork from. Producing it is a bake.	Built and stored by the platform.
Environment	Your named configuration of an artifact: egress policy, secrets, ready parameters.	Yours.
Sandbox	One live microVM, forked from a ready environment (or live-forked from another sandbox).	Yours: create → exec → fork → suspend → delete.

Three rules of thumb:

• Capacity is platform-managed. There is nothing to size or warm; capacity follows your workload.
• Bake = turning your container image into a ready-state artifact. Bringing your own image is a Pro capability.
• Demo = pick from the catalog. images() lists ready-to-run images; create a sandbox from any of them instantly — no bake, no build step.

On today's wire, an artifact + environment pair surfaces as a template (the id you pass on create); /v1/templates remains a working alias throughout the API.

Sandboxes

A sandbox is one microVM: a real virtual machine with its own kernel, isolated from the host and from every other sandbox by hardware virtualization (KVM). In the API a sandbox has an opaque id like sbx_9f2a1c7b3e40 and moves through a small lifecycle — running, suspended, deleted. See Sandbox lifecycle.

Every sandbox on every tier is the same Firecracker microVM. Collimate gates concurrency, session duration, and support by plan — never isolation or performance.

Fork-on-demand (why create is fast)

Most sandbox platforms cold-boot a VM when you ask for one — hundreds of milliseconds to seconds. Collimate instead keeps a warm template resident and forks it copy-on-write at request time:

1. A template is booted once and held warm.
2. On create, Collimate forks it. The child shares the template's memory pages copy-on-write and is ready in single-digit milliseconds.
3. The child only allocates its own RAM for the pages it actually writes.

So a new sandbox is off your critical path, and because forks share the template's pages, one host holds far more concurrent sandboxes than a boot-per-sandbox model.

Live fork (why fork beats replay)

Fork-on-demand starts a sandbox from a pristine template. Live fork goes further: it forks a sandbox you have already been driving, mid-flight, into N copy-on-write children — and each child inherits the parent's live process memory. Installed packages, a loaded model, a warmed cache, a browser mid-page: the clone has all of it, without reinstalling or replaying anything.

The replay tax

To branch an episode, the naive approach boots a fresh VM and re-runs the whole history to reach the branch point. That cost grows with episode length. Live fork pays it once: reach the state, then fork it into as many isolated children as you need. This is the single capability with no equivalent in a filesystem-snapshot sandbox — those drop process memory on the floor.

Live fork is the headline for both audiences: an agent forks a prepared workspace to explore many actions; a trainer forks a mid-rollout state for tree search or best-of-N. See Live fork.

Templates

A template is the image a sandbox is forked from — a booted guest with your runtime and dependencies ready to go. On the managed cloud there are two ways to get one:

• Pick from the catalog (every tier, the whole story on Demo): images() lists the ready-to-run images the platform keeps warm — create a sandbox from any of them instantly.
• Bake your own (Pro): register your OCI image and Collimate bakes it into a ready-state artifact — booted, warmed, checkpointed — that the fleet forks from.

On the Pro tier you register your own OCI images. See Templates.

Capacity follows your demand

Collimate keeps capacity ready where your work is, so a new sandbox forks instantly instead of re-warming a multi-gigabyte environment from cold. Capacity is platform-managed: you never size it, and it follows your workload.

Layer-preserving template storage

Real workloads are not one environment — they are a library of variants that share a common base (the same Python/CUDA/toolchain image plus a thin task diff). Collimate stores templates content-addressed and layer-preserving: the shared base is held once, each variant is just its diff, and distributing a new variant moves only that diff. Hundreds of environment variants cost close to one base image.

Running work in a sandbox

When you exec against a sandbox, Collimate:

1. Materializes any files into the guest.
2. Runs your command (a shell string), code (via the template's interpreter), or commands (argv lists, in order).
3. Captures stdout, stderr, and the exit_code, and returns them with timing — plus the CRNG seed the exec ran with, for deterministic replay.

Within one sandbox, execs are serialized (one at a time, FIFO); files and processes persist between calls. Across sandboxes they run concurrently up to your plan's concurrency cap. See Running code.

The two front doors

Agentic API + MCP

REST at api.collimate.ai, a Python SDK, and a hosted MCP endpoint at mcp.collimate.ai. Create → exec → fork → suspend/resume, driven by an agent or a human.

collimate-rl SDK

The collimate-rl Python SDK drives the same fleet for rollout workloads: connect() for the managed cloud and Sandbox for the in-worker hot path.

What's next

• Authentication — get a key, understand the tiers.
• Sandboxes quickstart — first sandbox in five minutes.
• Live fork — the headline capability, in depth.
• API reference — every endpoint and field.