Set the sandbox's timeline content-capture setting

Commands, exit codes, durations, desktop action metadata and lifecycle events are always recorded. Content capture is off by default. Enabling it additionally records best-effort-masked command output and typed text, plus screenshot thumbnails. It affects only future events.

PUT/v1/sandboxes/{sandbox}/timeline

Authorization

AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Path parameters

sandboxstringrequired

Sandbox ID (sbx_...) or name.

Request body

requiredapplication/json

capture_contentbooleanrequired

Responses

200

The sandbox with its updated setting.

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. 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), 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), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired

default

Error.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

Request

curl -X PUT 'https://api.pols.so/v1/sandboxes/string/timeline' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "capture_content": true
}'

const response = await fetch("https://api.pols.so/v1/sandboxes/string/timeline", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"capture_content\": true\n}"
});

import requests

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

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