Sandboxes
The compute ledger behind runtimes, evaluations, and worlds — where compute state, billing, and provider identity live.
Every time the platform reserves compute, it creates or updates a sandbox record. Interactive runtimes, evaluation environments, evaluation agent loops, Worlds backends — they all write to the same ledger. The sandbox tells you what ran, for how long, under which provider, and what it cost.
Higher-level surfaces decide why the compute exists; sandboxes just record that it exists.
| Kind | Purpose |
|---|---|
runtime | Backs an interactive runtime or an evaluation agent loop. |
task | Runs task-style compute: evaluation environments, training, and optimization jobs. |
world | Runs a Worlds backend for manifest and trajectory generation. |
States
Section titled “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. |
A sandbox transitions to killed when you delete it explicitly or
when it times out. Records persist after termination — the row stays
for audit and billing.
Why a sandbox paused
Section titled “Why a sandbox paused”When a sandbox is paused, the record carries a pause_reason:
| Reason | Cause |
|---|---|
user | Someone paused the runtime or sandbox explicitly. |
timeout | The sandbox hit its expiry window and was auto-paused. |
insufficient_credits | The org’s credit balance reached zero; running sandboxes were auto-paused. |
member_limit_exceeded | Workspace membership limit was hit and compute was auto-paused. |
Billing
Section titled “Billing”Credit accrual is settled from the sandbox record.
| Field | Meaning |
|---|---|
billed_credits | Credits already deducted, persisted on the sandbox row. |
running_credits | Derived from runtime duration since the last deduction. |
estimated_total_credits | billed_credits + running_credits — the projected total cost. |
Deduction is atomic — the platform updates the balance and row in a single SQL operation, so concurrent agents can’t overdraw.
Providers
Section titled “Providers”| Provider | Where it runs | Notes |
|---|---|---|
e2b | SaaS and staging | Primary hosted provider with custom sandbox templates. |
docker | Local / self-hosted | Uses the local Docker daemon. |
opensandbox | Self-hosted | Dreadnode’s open sandbox runtime for self-hosted clusters. |
Provider state can change before the sandbox ledger catches up. Every 60 seconds, Dreadnode
reconciles against the provider your deployment is configured for: on E2B it compares the
environment inventory, and on Docker or OpenSandbox it checks each locally running instance. If the
provider cannot give a definitive answer, Dreadnode keeps the last known state and retries on the
next cycle, so a missing instance can appear running temporarily.
When the provider reports an instance as dead but still allocated — a failed OpenSandbox pod, an exited Docker container — Dreadnode asks the provider to release it so the pod, volume, or container layer isn’t stranded. Releasing it discards that instance’s provider-side logs, so retrieve logs from a dead sandbox before the next cycle if you need them.
IDs and inventory
Section titled “IDs and inventory”Two IDs are worth keeping straight:
- the Dreadnode sandbox UUID on runtime and evaluation records
- the provider sandbox ID used for logs and provider-level operations
dn sandbox commands take the provider sandbox ID.
In the App, select a sandbox ID to open its bookmarkable detail view. The view includes lifecycle and credit timing, provider credential timing, and evaluation lineage when an evaluation created the sandbox.
Relationship to runtimes
Section titled “Relationship to runtimes”An interactive runtime points at one sandbox at a time. Starting a runtime provisions one; resetting terminates and unlinks it. The sandbox record survives termination — the runtime stays, the compute is gone.
For the interactive control surface, start from the runtime. Use the sandbox ledger when the question is “what compute existed, and what did it cost?”