Delete a sandbox and its disk

DELETE/v1/sandboxes/{sandbox}

Authorization

AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Path parameters

sandboxstringrequired

Sandbox ID (sbx_...) or name.

Responses

202

Accepted; the sandbox is being deleted.

idstringrequired

namestring | null

Unique among the org's sandboxes that are not deleted. Given or generated (an adjective and an animal, like braveotter); null only for sandboxes deleted before every sandbox had a name.

host_labelstring | null

What the edge serves the sandbox on besides its ID: https://<host_label>-<port|desktop|cdp>.<sandbox domain>. A generated adjective and animal with a random suffix of four lowercase letters and digits: the sandbox's generated name, like braveotterk3f9 for braveotter, or for a sandbox given a name a generated one, so that a given name is never part of an address. Set at create and never changed, a rename included; unique across all orgs and never reused. Null for sandboxes deleted before sandboxes had host labels.

sizeSizerequired

Sandbox size. small: 2 vCPU, 4 GiB RAM, 20 GiB disk. default: 4 vCPU, 8 GiB, 50 GiB. large: 8 vCPU, 16 GiB, 100 GiB. xlarge: 16 vCPU, 32 GiB, 200 GiB. A create that names no size gets small, or the smallest size whose disk holds the template; a sandbox keeps its size for life.

Allowed:smalldefaultlargexlarge

vcpusintegerrequired

memory_mibintegerrequired

disk_gibintegerrequired

template_idstring | null

The template it was created from; null for forks.

source_sandbox_idstring | null

The sandbox it was forked from.

statusSandboxStatusrequired

Where the sandbox actually is. pending means not created in the runtime yet, or still booting. running means booted: its guest agent answers, so exec and file calls work. A booting sandbox keeps its previous status, but its running interval (and billing) starts when the VM starts. standby means its VM is frozen with its memory kept because it was idle; the next call that needs it wakes it (see Standby above). error means the reconciler gave up; delete it.

Allowed:pendingrunningstoppeddeletederrorstandby

desired_stateDesiredStaterequired

standby is never asked for through the API: the control plane sets it for an idle sandbox and sets running again to wake it.

Allowed:runningstoppeddeletedstandby

last_errorstring | null

env_keysstring[]required

Names of the environment variables set on the sandbox (values are never returned). Empty once the sandbox is deleted, because deleting a sandbox erases its environment.

secretsstring[]required

Names of the vault entries the sandbox gets as environment variables. Their values are read from the vault when the VM is created; replacing an entry later does not change this sandbox.

capture_contentbooleanrequired

Whether future timeline events may include command output, typed text and screenshot thumbnails. False by default. Commands, exit codes, durations, desktop action metadata and lifecycle events are recorded either way.

egressEgressPolicyrequired

A sandbox's outbound network policy, chosen at create or fork and immutable thereafter.

Show properties

modeEgressModerequired

What a sandbox may reach on the network. default: the public internet. allowlist: only the destinations in allow. none: no outbound traffic. In every mode, private (RFC 1918), CGNAT (100.64.0.0/10), loopback, link-local (169.254.0.0/16, including the cloud metadata address 169.254.169.254) and IPv6 unique-local and link-local destinations, the sandbox host and the management plane are blocked, along with multicast, limited broadcast and outbound SMTP (TCP port 25). Host-local DHCP and required neighbor discovery remain available. Only default mode can use the host resolver; allowlist and none block it. For DNS in allowlist mode, list a public resolver's CIDR and configure the sandbox to use that resolver.

Allowed:defaultallowlistnone

allowstring[]

Only with mode allowlist, and then required: destination IPv4 or IPv6 CIDR prefixes (for example 203.0.113.7/32 or 2001:db8::/32). Single addresses need /32 or /128; bare IPs and hostnames are not supported. Entries that overlap a built-in blocked range are refused. Additional operator-denied destinations remain blocked by the runtime even when listed here. Returned in canonical CIDR form.

max items 64

created_atstring<date-time>required

updated_atstring<date-time>required

started_atstring<date-time> | null

When the current (or last) run started; standby does not end a run.

standby_atstring<date-time> | null

When the sandbox went to standby, while its status is standby.

stopped_atstring<date-time> | null

deleted_atstring<date-time> | null

expires_atstring<date-time> | null

When the sandbox is deleted automatically, running or stopped, set by ttl_seconds at create or fork; null means never. Deletion starts within seconds of this time and is the same as DELETE /v1/sandboxes/{sandbox}: the VM, its disk and its snapshots are removed and metering stops. It waits while a fork of the sandbox or a template from it is still being made; the sandbox is stopped meanwhile.

statsResourceStats

One sample of a running sandbox's resource use, as stats on a sandbox (present while it runs and has a recent sample) and in GET /v1/sandboxes/{sandbox}/stats.

Show properties

sampled_atstring<date-time>required

cpu_percentnumber<double>

Share of the sandbox's vCPUs that were busy, averaged since the previous sample: 100 means all of them. Absent in the first sample after the sandbox starts.

cpu_coresnumber<double>

The same as a number of busy vCPUs, for example 1.5. Absent with cpu_percent.

memory_used_bytesinteger<int64>required

Memory in use inside the VM, as its guest agent reports it.

memory_total_bytesinteger<int64>required

Memory the guest sees (slightly less than the size's RAM, which the guest kernel reserves part of).

disk_used_bytesinteger<int64>required

Space the root disk volume takes in the host's storage pool, as the pool reports it. On a copy-on-write clone (a sandbox created from a template, or a fork) this can leave out blocks it still shares with its origin. 0 when the host does not report it.

disk_total_bytesinteger<int64>required

Size of the root disk.

429

Rate limited (rate_limited): too many requests or failed authentications from this address, too many requests or lifecycle calls for this org, or too many of its exec, file, computer and CDP calls in progress at once. Retry after Retry-After seconds.

errorobjectrequired

Show properties

codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), withdrawal_consent_required (409, a consumer orders a top-up or the subscription only with withdrawal_consent), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired

controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties

heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

default

Error.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties

heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

Request

curl -X DELETE 'https://api.pols.so/v1/sandboxes/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch("https://api.pols.so/v1/sandboxes/string", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.delete(
    "https://api.pols.so/v1/sandboxes/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

{
  "id": "sbx_3k9x2m1q8zt4",
  "name": "braveotter",
  "host_label": "braveotterk3f9",
  "size": "small",
  "vcpus": 0,
  "memory_mib": 0,
  "disk_gib": 0,
  "template_id": "string",
  "source_sandbox_id": "string",
  "status": "pending",
  "desired_state": "running",
  "last_error": "string",
  "env_keys": [
    "string"
  ],
  "secrets": [
    "string"
  ],
  "capture_content": true,
  "egress": {
    "mode": "default",
    "allow": [
      "203.0.113.0/24"
    ]
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "started_at": "2019-08-24T14:15:22Z",
  "standby_at": "2019-08-24T14:15:22Z",
  "stopped_at": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "stats": {
    "sampled_at": "2019-08-24T14:15:22Z",
    "cpu_percent": 0.1,
    "cpu_cores": 0.1,
    "memory_used_bytes": 0,
    "memory_total_bytes": 0,
    "disk_used_bytes": 0,
    "disk_total_bytes": 0
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "control": {
      "held": true,
      "holder": "Ada",
      "since": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z"
    }
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "control": {
      "held": true,
      "holder": "Ada",
      "since": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z"
    }
  }
}