Skip to main content
Destroy a sandbox

Authorizations

Authorization
string
header
required

BoxRouter API key; never an upstream provider key.

Path Parameters

sandbox_id
string
required

Workspace-owned BoxRouter sandbox ID, not an upstream ID.

Minimum string length: 1
Pattern: ^[^\u0000]*$

Query Parameters

discard_unsaved
boolean
default:false

Destroy even if saving the attached volume fails, discarding unsaved changes.

Response

The sandbox after the provider accepted the destroy.

A sandbox created from a settled body, returned by create, restore, get and list. Required fields are present; fields with no value are null, never absent. Optional fields may be absent when their source is not known. Listings do no provider I/O: they show the latest durably recorded state, and native_state, route.selection and recorder are null. Detail responses observe the provider live and record the normalized state unless a concurrent lifecycle change supersedes the read.

id
string
required
Required string length: 1 - 128
Pattern: ^[^\u0000]*$
state
enum<string>
required

Clients must tolerate values they do not know. A sandbox the provider stopped, or one stopped for being idle that can be started again, reads paused; resume brings either back.

Available options:
creating,
running,
paused,
destroying,
destroyed,
error,
unknown
state_reason
enum<string> | null
required

Why it is in this state. external is a change made at the provider, behind BoxRouter's back.

Available options:
requested,
lifetime,
retention,
idle_shutdown,
external,
null
failure
object | null
required

The provider failure recorded with state=error, or null when no recorded failure explains the current state. Present on create, detail and list responses; list reads return the durable value without calling the provider.

native_state
string | null
required
observed_at
string<date-time>
required

Time the state source for this response was read: the owned-record lookup time for a list response, or the live provider-observation time for a detail response.

state_recorded_at
string<date-time> | null
required

Timestamp of the durable state source used for this response. This can be an existing lifecycle or lifetime record when the returned public state is derived from that source, and may predate observed_at. Null when no source timestamp is available or a concurrent lifecycle change supersedes the detail read.

created_at
string<date-time> | null
required

Time Cloud sent the first create request when that edge is available; otherwise the sandbox record's created time.

ready_at
string<date-time> | null
required

Time Cloud received the first create response; when that edge is unavailable, the sandbox record's ready time. Null while creating. List and detail responses use the same value.

ended_at
string<date-time> | null
required

Time Cloud received the last destroy response; when that edge is unavailable, Cloud's record of confirmation or first observation that the sandbox was gone. Null while the sandbox has not ended. List and detail responses use the same value.

labels
object
required
lifetime
object
required

How long the sandbox may live. It counts from the provider's create, as with the provider's own SDK (BoxRouter's clock starts when it sends the create). Whether paused time counts depends on the provider.

route
object
required

The adapter that made this sandbox. Support questions start at adapter_version. A sandbox with no recorded contract still names its provider and account; its class and adapter_version are null.

contract
object | null
required

Null for a record with no recorded contract, such as one a provider-native route created.

request
object
required

The recorded creation request after server-side expansion and defaulting, without request-only secret values, environment values or labels. A sandbox can outlive the create-request schema that was current when it was made, so this historical snapshot accepts fields from earlier contract versions. Clients should interpret only fields they recognize and preserve unknown fields when displaying or storing the snapshot.

hidden_secrets
object | null
required

Public metadata for the request-only secret values, keyed by their submitted names. Each result contains only a placeholder and its allowed hosts. Null when the create submitted no secret values.

tcp_ports
object[] | null
required

Public host and port for each requested TCP listener, in request order.

recorder
object | null
required

A tally of the gate calls made on this sandbox, allowed and refused, with the requirements line those calls relied on. It only tallies: it switches no gate on.

limits
object
required
expires_at
string<date-time> | null

Enforced deadline from the recorded lifetime budget, including extensions. This is the same deadline exposed as lifetime.ends_at; null when no deadline is known.

created_at_source
enum<string> | null

Where created_at came from. Null when created_at is null. Always BoxRouter's own record.

Available options:
provider,
published,
measured,
recorded,
calculated,
unknown
created_at_how
string | null

One sentence saying how created_at was determined. Null when created_at is null.

Minimum string length: 1
created_at_step
integer | null

Null because created_at comes from a recorded lifecycle edge or Cloud's record.

Required range: x >= 1
ready_at_source
enum<string> | null

Where ready_at came from. Null when ready_at is null. Lifecycle edges and Cloud's own record are recorded.

Available options:
provider,
published,
measured,
recorded,
calculated,
unknown
ready_at_how
string | null

One sentence saying how ready_at was determined. Null when ready_at is null.

Minimum string length: 1
ready_at_step
integer | null

Null because ready_at comes from a recorded lifecycle edge or Cloud's record.

Required range: x >= 1
ended_at_source
enum<string> | null

Where ended_at came from. Null when ended_at is null. Lifecycle edges and Cloud's own record are recorded.

Available options:
provider,
published,
measured,
recorded,
calculated,
unknown
ended_at_how
string | null

One sentence saying how ended_at was determined. Null when ended_at is null.

Minimum string length: 1
ended_at_step
integer | null

Null because ended_at comes from a recorded lifecycle edge or Cloud's record.

Required range: x >= 1
cost_source
enum<string> | null

Where cost came from. Null when cost is null. provider for a reported cost, calculated for a worked-out one, unknown when no cost could be worked out. The cost_step is 1 for a provider figure, then 2 provider times, 3 a checked billing boundary, 4 a range, 5 unknown.

Available options:
provider,
published,
measured,
recorded,
calculated,
unknown
cost_how
string | null

One sentence saying how cost was determined. Null when cost is null.

Minimum string length: 1
cost_step
integer | null

The position of the source in BoxRouter's source order for this value, 1 being the best. Null when the value is BoxRouter's own record rather than a pick between sources.

Required range: x >= 1
origin
object

Durable creation provenance. Omitted when the source is not known.

name
string | null

Sandbox name from labels.name, when set.

resources
object

Resolved CPU, memory and disk resources; null values mean unknown.

image
object | null

The image the sandbox runs and where that is known from. Null when nothing records it. Absent from responses of a Cloud that does not report it yet.

image_setup
object

Present only when this start waited for image setup on its chosen provider.

usage
Usage record · object

What the sandbox used: its size, its running time per state, how often it was created, each fact with the source it came from. Null when nothing has been recorded or the response does not carry it. Absent from responses of a Cloud that does not report it yet.

cost
Cost · object

What the sandbox cost, with one word saying how far to trust it. Create and detail responses carry the full cost with its working; list rows carry only its label and total, from the same calculation. One object serves both, so the schema accepts either shape anywhere: a client that needs the working reads the detail. Null when no cost has been worked out. Absent from responses of a Cloud that does not report it yet.

charge
object | null

What BoxRouter charged to the workspace's credits for this sandbox: the reservation while it runs, then the amount charged once the provider's records are in. Present on credit-funded sandboxes in detail and list responses. Null for a sandbox paid with the workspace's own provider account (BYOK), for a credit-funded one whose reservation was released without a charge, and for one whose ledger record cannot be verified: BoxRouter reports no charge rather than a guess. cost still reports the provider's cost. Absent from create and other responses, and from a Cloud that does not report it yet. It is the ledger's amount, never derived from cost or from BoxRouter's clock.

funded_until
string<date-time> | null

The time up to which the workspace's credits are reserved for this sandbox. A sandbox created without lifetime_seconds renews its reservation hourly while the balance covers it, so this moves later at each renewal; the sandbox ends at this time if the balance could not cover another hour. For a sandbox created with lifetime_seconds it is the end of that lifetime. Null for a sandbox paid with the workspace's own provider account (BYOK), which has no reservation. A reservation is a hold on the balance, never a cost: charge reports the credits reserved and then charged. Present on create and on detail and list reads; absent from a Cloud that does not report it yet.

connectable
boolean

Whether interactive access to this sandbox is offered: a terminal, commands, files and processes. False for a sandbox an Actions job runs in, which holds that job's token and secrets; Cloud refuses these operations on it, before and after the job ends, and the dashboard shows no Connect action. True for every other sandbox. One rule, decided by Cloud; clients do not infer it from origin, which an Actions runner that has not yet served a job does not have. Present on detail and list reads; absent from a Cloud that does not report it yet.

volume
object | null

Present when the sandbox is attached to a BoxRouter Volume.

operation_id
string | null

Present on a destroy response: the workspace-owned destroy operation while lifecycle work remains (state is destroying), null once the destroy is confirmed. Absent from every other response.

Minimum string length: 1
account
object

Present only while the account's key no longer works (section 7); that sandbox's calls then answer account_unhealthy and state is unknown.