Core concepts

Eleven objects carry the whole product. Everything in the API is one of these, or an action on one.

Organization

The billing entity and the top of the ownership tree. One organization holds one price list, one payment method, one credit balance, one spend cap and one set of members with roles. Everything else belongs, transitively, to exactly one organization.

An organization is never deleted while it has an unpaid balance or a running session.

Project

The unit of isolation inside an organization: production, staging, a per-customer project, a per-team project. Projects carry their own API keys, policies, templates, quotas and default region. Usage rolls up to the organization but stays attributable to the project.

Use separate projects wherever you would want separate blast radius, separate egress rules, or separate usage reporting.

API key

A credential bound to one project, carrying an explicit scope set (sessions:write, runs:write, usage:read, admin:write, …).

Keys are shown once at creation and stored only as a hash. Rotation is additive: create the new key, roll traffic, revoke the old one. See authentication.

End user

The customer's own customer. An optional end_user_id on any session or run attributes the usage to that identity, which is what makes per-seat metering, per-seat quotas and per-seat spend caps possible.

Session

A live runtime at one tier, with an identity, a lifetime and a bill. Created explicitly with POST /sessions, or implicitly and invisibly by a one-shot POST /runs.

A session owns:

• a tier, fixed at creation and never changed
• a template, which determines the rootfs and preinstalled toolchain
• resources — vCPU, memory, optional GPU
• an idle timeout and a maximum lifetime, both enforced server-side
• an optional volume mounted at /workspace
• a policy binding — egress rules, allowlists
• an optional end user for attribution

Sessions are billed for wall-clock seconds in running state, plus the resource meters they accrue. A paused session is billed only for its retained storage. See session lifecycle.

Run

One bounded execution inside a session: evaluate this code, run this command, perform this browser action batch. A run has a status, an exit code, captured stdout and stderr, a duration and its own usage block.

Runs are the natural unit for an agent loop: one model turn maps to one run. They are also the unit the API streams — logs arrive over SSE while the run is in flight.

POST /runs without a session_id is the one-shot form: the platform creates a session, runs, returns and releases. Cheaper to write, more expensive per call if you do it in a loop, because each one pays a start.

Template

An immutable, versioned base image for a tier: rootfs, preinstalled toolchain, default environment, default working directory. tpl_base_python_3_12, tpl_base_ubuntu_24_04, tpl_browser_chromium_129, tpl_desktop_xfce.

Organizations can publish private templates built on the platform's bases. Templates are built once, cached per region, and pre-baked into warm pools — which is why a template that is not in the warm pool starts measurably slower. See scheduler and warm pools.

Volume

A persistent disk that outlives sessions. Attached to at most one session at a time, mounted at /workspace by default. Sized at creation, resizable up.

Use a volume when an agent needs continuity — a repository it keeps working in, a dataset it keeps querying. Use a snapshot instead when you need many sessions to start from the same prepared state.

Volumes are billed per GiB-month of provisioned size, whether or not a session is attached.

Snapshot

A restorable point-in-time image of a session: filesystem always, memory state optionally for tiers 2 to 4. Restoring from a memory snapshot is how a tier 4 desktop reaches an application-ready state in seconds instead of a minute.

Snapshots are immutable, regional, and billed per GiB-month of compressed size.

Policy

A named, versioned bundle of restrictions bound to a project or an individual session:

• Egress policy — the destination allowlist, DNS rules and bandwidth ceiling
• CLI allowlist — which binaries a tier 2 session may execute
• Tool allowlist — which MCP tools a tier 0 agent may invoke
• Secret scope — which secrets may be injected, and into which tiers

Policies are evaluated at admission and enforced continuously in the data plane. A policy change applies to new sessions immediately and to running sessions at the next enforcement interval. See policy engine.

Usage event

The atomic billing record: one meter, one quantity, one time window, one session, one optional end user. Emitted by the node agent, deduplicated on (session_id, meter, window_start), aggregated into minute buckets, rated against the organization's price list, rolled up daily, invoiced monthly. See metering model.

Webhook event

A delivered notification of a state change: session.running, session.failed, run.succeeded, quota.threshold_reached, invoice.finalized. Signed, retried with exponential backoff, replayable from the events API for 30 days. See webhooks.