Create a sandbox from a template and start it

Enforces the org’s quotas (running sandboxes, total sandboxes), while billing is off for the org its monthly sandbox-hours (403 quota_exceeded), and, once billing is switched on for the org (billing_enabled on /v1/balance; on for new orgs), its balance (402 insufficient_credit unless it is positive) and, for a trial org (trial), the trial limits: it may run one small or default sandbox at a time and hold 20 GiB of disk (403 trial_limit), and all trial orgs together may reserve 8 GiB of host memory at once, overcommitted like the hosts’ (12 GiB at the default --memory-overcommit of 1.5; the configured value is trial_credit.limits.total_memory_gib on /v1/balance): a start beyond that is refused with 429 trial_capacity and a Retry-After, and may pass when retried. While the host is short of memory, any start is refused with 429 host_capacity and a Retry-After. The egress policy defaults to mode default. secrets must name existing vault entries (400 otherwise; 503 when the deployment has no vault key). With ttl_seconds, the sandbox is deleted once it expires (see expires_at).

POST/v1/sandboxes

Authorization

AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Request body

application/json

nameSandboxName

Lowercase letters, digits and dashes, starting with a letter; unique among the org's sandboxes that are not deleted (409 conflict otherwise). Without one, the sandbox gets a generated name: an adjective and an animal written together, like braveotter.

matches ^[a-z][a-z0-9-]{0,62}$

sizeSize

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

templatestring

Template ID or name. Defaults to the ubuntu-24.04 system template.

envobject

Environment variables for every exec in the sandbox. Prefer secrets for API keys and passwords: env values are stored as given.

secretsSecretNames

Vault entries to set as environment variables of the same name. Together with env (and, for a fork, the source's environment and entries) at most 100 variables; a name may not also be in env.

max items 100

egressEgressPolicy

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

ttl_secondsTTLSeconds

Delete the sandbox this many seconds after the request, whether it is running or stopped, so a client that never deletes it (for example because it crashed) does not leave it running and billed. From 60 seconds to 30 days; omit for no expiry. The response's expires_at says when.

min 60 · max 2592000

capture_contentboolean

Opt into recording command output, typed text and screenshots in the timeline.

default: false

Responses

201

Accepted; the sandbox is being created.

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

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

Allowed:defaultallowlistnone

allowstring[]

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 POST 'https://api.pols.so/v1/sandboxes' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "braveotter",
  "size": "small",
  "template": "string",
  "env": {
    "property1": "string",
    "property2": "string"
  },
  "secrets": [
    "ANTHROPIC_API_KEY"
  ],
  "egress": {
    "mode": "default",
    "allow": [
      "203.0.113.0/24"
    ]
  },
  "ttl_seconds": 3600,
  "capture_content": false
}'

const response = await fetch("https://api.pols.so/v1/sandboxes", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"name\": \"braveotter\",\n  \"size\": \"small\",\n  \"template\": \"string\",\n  \"env\": {\n    \"property1\": \"string\",\n    \"property2\": \"string\"\n  },\n  \"secrets\": [\n    \"ANTHROPIC_API_KEY\"\n  ],\n  \"egress\": {\n    \"mode\": \"default\",\n    \"allow\": [\n      \"203.0.113.0/24\"\n    ]\n  },\n  \"ttl_seconds\": 3600,\n  \"capture_content\": false\n}"
});

import requests

response = requests.post(
    "https://api.pols.so/v1/sandboxes",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"name\": \"braveotter\",\n  \"size\": \"small\",\n  \"template\": \"string\",\n  \"env\": {\n    \"property1\": \"string\",\n    \"property2\": \"string\"\n  },\n  \"secrets\": [\n    \"ANTHROPIC_API_KEY\"\n  ],\n  \"egress\": {\n    \"mode\": \"default\",\n    \"allow\": [\n      \"203.0.113.0/24\"\n    ]\n  },\n  \"ttl_seconds\": 3600,\n  \"capture_content\": false\n}",
)

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"
    }
  }
}