Runtimes
Workspace-scoped resources that hold sessions, capability bindings, and project grouping across ephemeral sandbox compute.
A runtime is the durable thing you work with. The sandbox behind it is disposable.
When you open a session, install capabilities, and pick an agent, those choices live on the runtime. The compute underneath can be started, paused, resumed, or replaced — your sessions and bindings come back every time.
Why the split matters
Section titled “Why the split matters”- the runtime is the thing you control
- the sandbox is the thing you pay for
- the session is the thing you resume
If those were one object, every reset would discard conversation history and every compute failure would look like lost project state. Splitting them keeps the three lifecycles independent.
States
Section titled “States”A project can group any number of runtimes, and each runtime points at zero or one sandbox at a time. Sandbox provisioning is lazy — starting a runtime is what actually reserves compute.
| Runtime status | Sandbox | Meaning |
|---|---|---|
idle | none | No compute is reserved. The runtime is clean or reset. |
running | active | A sandbox is provisioned and executing. |
paused | suspended | The sandbox is paused. Credits stop accruing. |
Lifecycle
Section titled “Lifecycle”| Action | Effect | Needs a sandbox? |
|---|---|---|
start | Provisions a sandbox. Injects any secrets declared in the runtime’s configuration. | No |
pause | Suspends the current sandbox. Credits stop. | Yes |
resume | Restores the paused sandbox. | Yes |
reset | Terminates the sandbox and returns the runtime to idle. | Yes |
keepalive | Extends the sandbox expiry to prevent automatic timeout. | Yes |
start on a running runtime returns the sandbox that is already
there; it never replaces it. If the durable configuration has changed
since that sandbox was created, the response says so, and applying the
change is an explicit reset followed by start.
See Managing runtimes for the workflows, and Configuration for what persists across sandbox replacement. Runtimes in Chat covers the same lifecycle as the browser presents it, including what each state costs and where the cold start comes from.
Runtimes belong to one person
Section titled “Runtimes belong to one person”A runtime is owned by whoever created it. You can see every runtime in a workspace, including your teammates’, but only the owner can start, pause, resume, reset, or reconfigure one, or change what capabilities it has installed.
Two people working in the same project therefore get a runtime each rather than sharing one. Starting a runtime injects the owner’s secrets into the sandbox, so a shared runtime would run one person’s agent in an environment holding another person’s credentials.
Opening a project you have not worked in before shows you no runtime, even when a teammate already has one running there. Starting from that state creates yours. You can hold more than one runtime in the same project if you want separate environments.
Capability bindings stay with the runtime
Section titled “Capability bindings stay with the runtime”Capabilities you install on a runtime survive the full sandbox lifecycle. Pause, resume, reset, or reprovision — the bindings are there again when the next sandbox starts.
See Capabilities for how to author a bundle.