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 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 is still meaningful: if the durable
configuration has changed since the sandbox was created, the old
sandbox is replaced with a fresh one that matches.
See Managing runtimes for the workflows, and Configuration for what persists across sandbox replacement.
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.