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. |
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.
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?”