Sandboxes

Sandboxes are the persisted records of provider-backed compute instances on Dreadnode. Every piece of compute — whether it backs an interactive runtime, an evaluation item, a task environment, or a Worlds job — is tracked as a sandbox record in a shared ledger.

What a sandbox is

A sandbox is a generic compute record. It captures the provider instance identity, lifecycle state, billing data, and metadata for a single compute allocation. Sandboxes do not own business logic for any specific use case; they are the infrastructure layer that other domains build on.

Three sandbox kinds exist:

Kind	Purpose
runtime	Backs an interactive runtime for agent sessions and capability execution
task	Runs a task environment (Docker Compose) for evaluation items
world	Runs a Worlds backend for manifest and trajectory generation

The sandbox domain owns generic provider lifecycle — provisioning, pausing, resuming, terminating, and timeout enforcement. Higher-level domains (runtimes, evaluations, worlds) own the durable resources that reference sandboxes.

Sandbox and runtime relationship

Interactive runtimes reference a current sandbox. The runtime is the stable identity; the sandbox is the replaceable compute backing it.

• A runtime starts with no sandbox (idle state)
• Starting a runtime provisions a sandbox and links it
• Resetting a runtime terminates its sandbox and unlinks it
• The sandbox record persists after termination for billing and audit

Write operations on interactive sandboxes — pause, resume, keepalive, delete — are exposed through the runtimes API, not the sandboxes API directly. This enforces the invariant that the runtime is the control point for interactive compute.

States

State	Meaning
running	The provider instance is active and consuming credits
paused	The provider instance is suspended; credits stop accruing
killed	The provider instance has been terminated (final state)

Sandboxes transition to killed when explicitly deleted, when they time out, or when the organization’s credit balance reaches zero.

Billing

Credit billing is settled from sandbox records:

• billed_credits — credits already deducted, persisted on the sandbox row
• running_credits — derived from active runtime duration since the last deduction
• estimated_total_credits — billed_credits + running_credits, the projected total cost

Credit deduction is atomic to prevent overdraw. When an organization’s balance reaches zero, all running sandboxes for that organization are terminated automatically.

Providers

Dreadnode supports two sandbox providers:

Provider	Environment	Notes
E2B	Production, staging	Primary provider. Custom sandbox templates for runtime, task, and worlds workloads. Webhook integration for lifecycle events.
Docker	Local development	Uses local Docker daemon. Configured via DOCKER_HOST, DOCKER_NETWORK, DOCKER_RUNTIME_IMAGE.

The provider abstraction means higher-level code interacts with sandboxes uniformly regardless of which provider is active.

API surface

Sandbox records are organization-scoped read-only resources:

• GET /api/v1/org/{org}/sandboxes
• GET /api/v1/org/{org}/sandboxes/{sandbox_id}
• GET /api/v1/org/{org}/sandboxes/{sandbox_id}/logs
• GET /api/v1/org/{org}/sandboxes/usage

The list endpoint supports filtering by state (running, paused, killed) and cursor-based pagination. The usage endpoint returns aggregate runtime seconds, session counts, and current-month usage.

For interactive sandbox lifecycle operations (start, pause, resume, reset, keepalive), use the runtimes API.