Create a sandbox from a template and start it

Enforces the org’s quotas (running sandboxes, total sandboxes, monthly hours). The egress policy defaults to mode default. secrets must name existing vault entries (400 otherwise; 503 when the deployment has no vault key).

POST/v1/sandboxes

Authorization

AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Request body

application/json

nameName

Lowercase letters, digits and dashes, starting with a letter.

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.

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

Responses

201

Accepted; the sandbox is being created.

idstringrequired

namestring | null

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.

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. error means the reconciler gave up; delete it.

Allowed:pendingrunningstoppeddeletederror

desired_stateDesiredStaterequired

Allowed:runningstoppeddeleted

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.

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) running interval started.

stopped_atstring<date-time> | null

deleted_atstring<date-time> | null

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), forbidden (403), quota_exceeded (403), not_found (404), conflict (409), rate_limited (429, see Retry-After), internal (500), runtime_error (502, the sandbox host failed), unavailable (503, the feature is not configured on this deployment), timeout (504, or 408 when a request body stalls).

messagestringrequired

default

Error.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

Request

curl -X POST 'https://api.pols.so/v1/sandboxes' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "size": "small",
  "template": "string",
  "env": {
    "property1": "string",
    "property2": "string"
  },
  "secrets": [
    "ANTHROPIC_API_KEY"
  ],
  "egress": {
    "mode": "default",
    "allow": [
      "203.0.113.0/24"
    ]
  }
}'

const response = await fetch("https://api.pols.so/v1/sandboxes", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"name\": \"string\",\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}"
});

import requests

response = requests.post(
    "https://api.pols.so/v1/sandboxes",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"name\": \"string\",\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}",
)

Response

{
  "id": "sbx_3k9x2m1q8zt4",
  "name": "string",
  "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"
  ],
  "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",
  "stopped_at": "2019-08-24T14:15:22Z",
  "deleted_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"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}