Runtimes

Runtimes are the durable interactive context for agent execution on Dreadnode. A runtime decouples the stable resource you interact with — where sessions, capability bindings, and project grouping live — from the ephemeral compute instance (sandbox) that backs it.

What a runtime is

A runtime is a workspace-scoped resource that represents a single interactive agent environment. In the current model, each project has exactly one runtime, created eagerly when the project is created.

The runtime itself is a lightweight record. It does not run anything on its own. Instead, it holds a reference to a current sandbox instance that is provisioned on demand and can be replaced without losing the runtime’s identity or configuration.

This matters because:

• Capability bindings persist across sandbox lifecycle — they are attached to the runtime, not the sandbox
• Sessions reference the runtime, not the underlying sandbox
• Sandbox instances can be discarded and recreated (via reset) while the runtime stays the same

Runtime and sandbox relationship

A runtime may reference zero or one sandbox at a time. Sandbox materialization is lazy — no compute is provisioned until you explicitly start the runtime.

Runtime status	Sandbox state	Meaning
idle	None	No sandbox exists. The runtime is clean or has been reset.
running	Active	A sandbox is provisioned and executing.
paused	Suspended	The sandbox is paused (preserving state) to save credits.

Starting a runtime provisions a sandbox. Pausing suspends the sandbox. Resuming restores it. Resetting discards the current sandbox entirely and returns the runtime to idle.

Lifecycle

Action	What happens	Requires existing sandbox?
Start	Provisions a new sandbox. Accepts optional secret_ids to inject user secrets into the sandbox environment.	No — transitions from idle to running
Pause	Suspends the current sandbox. Credits stop accruing.	Yes — returns 409 if no sandbox
Resume	Restores the paused sandbox.	Yes — returns 409 if no sandbox
Reset	Terminates the current sandbox and returns the runtime to idle.	Yes — returns 409 if no sandbox
Keepalive	Extends the sandbox expiry window to prevent automatic timeout.	Yes — returns 409 if no sandbox

Capability bindings

Capabilities installed on a runtime persist across the full sandbox lifecycle — pausing, resuming, resetting, and reprovisioning do not remove them. This means you can configure your runtime’s capabilities once and have them available every time you start or reset the sandbox.

Capability management is done through the runtime’s capability endpoints:

• Install a capability from the org inventory or public catalog
• Enable or disable an installed capability
• Update a capability binding’s configuration
• Uninstall a capability
• Resolve the full set of active capabilities (merged from all enabled bindings)

See Custom Capabilities for details on authoring capability bundles.

API surface

Runtimes are workspace-scoped API resources:

• GET /api/v1/org/{org}/ws/{workspace}/runtimes
• GET /api/v1/org/{org}/ws/{workspace}/runtimes/{runtime_id}
• POST /api/v1/org/{org}/ws/{workspace}/runtimes/{runtime_id}/start
• POST /api/v1/org/{org}/ws/{workspace}/runtimes/{runtime_id}/pause
• POST /api/v1/org/{org}/ws/{workspace}/runtimes/{runtime_id}/resume
• POST /api/v1/org/{org}/ws/{workspace}/runtimes/{runtime_id}/reset
• POST /api/v1/org/{org}/ws/{workspace}/runtimes/{runtime_id}/keepalive

Capability bindings on a runtime:

• GET /api/v1/org/{org}/ws/{workspace}/runtimes/{runtime_id}/capabilities
• POST /api/v1/org/{org}/ws/{workspace}/runtimes/{runtime_id}/capabilities
• GET /api/v1/org/{org}/ws/{workspace}/runtimes/{runtime_id}/capabilities/resolved
• PATCH /api/v1/org/{org}/ws/{workspace}/runtimes/{runtime_id}/capabilities/{binding_id}
• DELETE /api/v1/org/{org}/ws/{workspace}/runtimes/{runtime_id}/capabilities/{binding_id}