Get machine details

GET

sandboxes

{sandboxID}

curl --request GET \
  --url "https://api.bead.run/sandboxes/$SANDBOX_ID" \
  --header "X-API-Key: $BEAD_API_KEY"

{
  "alias": "<string>",
  "allowInternetAccess": {},
  "clientID": "<string>",
  "cpuCount": 123,
  "diskSizeMB": 123,
  "domain": {},
  "endAt": {},
  "envdAccessToken": "<string>",
  "envdUnresponsiveAtPause": true,
  "envdVersion": "<string>",
  "grace_deadline": {},
  "idle_timeout": {},
  "kind": "<string>",
  "last_activity": {},
  "lifecycle": {
    "autoResume": true,
    "onTimeout": "<string>"
  },
  "machine_state": "<string>",
  "memoryMB": 123,
  "metadata": {},
  "network": {
    "allowOut": [
      "<string>"
    ],
    "allowPublicTraffic": {},
    "denyOut": [
      "<string>"
    ],
    "dnsServers": [
      "<string>"
    ],
    "egressProxy": {
      "address": "<string>",
      "password": "<string>",
      "tls": {
        "caCert": "<string>",
        "enabled": true,
        "serverName": "<string>"
      },
      "username": "<string>"
    },
    "httpsPorts": [
      123
    ],
    "maskRequestHost": "<string>",
    "rules": {
      "<key>": [
        {
          "transform": {
            "headers": {}
          }
        }
      ]
    }
  },
  "pauseMode": "<string>",
  "paused_at": {},
  "sandboxID": "<string>",
  "startedAt": "<string>",
  "state": "<string>",
  "templateID": "<string>",
  "volumeMounts": [
    {
      "name": "<string>",
      "path": "<string>"
    }
  ],
  "wake_reason": {},
  "warnings": [
    {}
  ],
  "durability": {
    "mode": "<string>",
    "remoteCheckpoint": true,
    "checkpointIntervalSeconds": 123,
    "lastCommittedCheckpointAtMs": {},
    "checkpointAgeMs": {},
    "hostLost": true,
    "recoverable": true,
    "status": "<string>",
    "message": "<string>"
  },
  "preservation": {
    "status": "<string>",
    "operationID": "<string>",
    "billing": "<string>",
    "recovered": true,
    "code": "<string>",
    "terminal": true,
    "message": "<string>",
    "nextAction": "<string>"
  }
}

Authentication

Send your scoped bearer token in the Authorization: Bearer <BEAD_TOKEN> header, or send your API key in X-API-Key.

Parameters

string

required

Machine identifier returned by creation.

curl --request GET \
  --url "https://api.bead.run/sandboxes/$SANDBOX_ID" \
  --header "X-API-Key: $BEAD_API_KEY"

Response

200

Successfully returned the sandbox.

string

Alias of the template

boolean | null

Whether internet access was explicitly enabled or disabled for the sandbox. Null means it was not explicitly set. May be null.

string

required

deprecated

Identifier of the client

integer

required

CPU cores for the sandbox Format: int32. Minimum: 1.

integer

required

Disk size for the sandbox in MiB Format: int32. Minimum: 0.

string | null

Base domain where the sandbox traffic is accessible May be null.

string | null

required

Time when the sandbox will expire Format: date-time. May be null.

string

Access token used for envd communication

boolean

True when the snapshot a paused sandbox would resume from was taken while the sandbox guest agent was not responding. A plain resume of it is refused with 409 and error_code sandbox_snapshot_guest_agent_unresponsive, because restoring that memory would bring the unresponsive agent back; resume it without memory (memory: false), which cold-boots the sandbox from its disk. Omitted for a running sandbox and for a snapshot whose agent answered.

string

required

Version of the envd running in the sandbox

string | null

End of the credit grace period as an RFC 3339 timestamp, or null when funded. May be null.

integer | string | null

Seconds without activity before a persistent machine pauses, or never to disable idle pause. Persistent machines default to 900 seconds; numeric values must be 300–86400. May be null. Accepts integer or string (“never”).

string

Lifetime policy: temporary expires at its timeout; persistent retains state until explicit deletion or the end of credit grace. Allowed values: "temporary", "persistent".

string | null

Most recent activity as an RFC 3339 timestamp, or null when no activity was recorded. May be null.

object

Sandbox lifecycle policy returned by sandbox info.

Show Properties

boolean

required

Whether the sandbox can auto-resume.

string

required

Action taken when the sandbox times out. Allowed values: "kill", "pause".

string

Current lifecycle state including running, idle-paused, waking, credit-grace, lost, or deleted. Allowed values: "running", "idle-paused", "waking", "credit-grace", "lost", "deleted".

integer

required

Memory for the sandbox in MiB Format: int32. Minimum: 128.

object

String key/value labels attached to the machine. Agent setup and credential references use reserved bead.* keys. Additional keys accept string values.

object

Network configuration object. This deployment rejects an explicit network configuration with 501 unsupported_feature.

Show Properties

string[]

List of allowed destinations for egress traffic. Each entry can be a CIDR block (e.g. “8.8.8.8/32”), a bare IP address (e.g. “8.8.8.8”), or a domain name (e.g. “example.com”, “*.example.com”). Allowed entries always take precedence over denied entries. When allowOut contains a domain, the servers in dnsServers (8.8.8.8 by default) are also allowed.

boolean | null

Whether sandbox URLs accept traffic without the sandbox’s traffic access token. When omitted or null on create, the project’s default applies, which is true unless the project changed it. May be null.

string[]

List of denied CIDR blocks or IP addresses for egress traffic. Domain names are not supported for deny rules.

string[]

DNS servers the sandbox can reach when allowOut contains a domain. Each entry must be an IPv4 address, and all traffic to it is allowed. Omit it to allow the default nameserver 8.8.8.8, or pass an empty list to allow none. This does not change the sandbox’s /etc/resolv.conf. Maximum items: 10.

object | null

SOCKS5 proxy for sandbox egress. Outbound TCP is tunneled through the proxy after allow/deny filtering; the sandbox is unaware. Domain-matched flows use remote DNS (ATYP=domain). May be null.

Show Properties

string

required

SOCKS5 proxy address in host:port format (e.g. “proxy.example.com:1080”).

string

Optional SOCKS5 password (RFC 1929), max 255 bytes. Maximum length: 255.

object | null

TLS for the connection to the SOCKS5 proxy. The SOCKS5 negotiation and the tunneled traffic both run inside the TLS session, so the proxy credentials are not sent in the clear. This secures only the hop to the proxy; what the proxy does onward is its own concern. A half-close from the sandbox reaches the proxy as a TLS close_notify, not a TCP FIN, and a proxy that treats close_notify as a full close cuts the reply short. May be null.

Show Properties

string

One or more PEM-encoded certificates to verify the proxy against, for a proxy fronted by a private CA. These replace the system trust store, which is what is used when this is omitted. Set this to use the same certificate verification for every request. Maximum length: 8192.

boolean

required

Connect to the proxy over TLS. When false, no other field in this object may be set.

string

Name to verify the proxy certificate against, and to send as SNI. Defaults to the host part of address. Set this only when the certificate does not match the address the proxy is reached at. Maximum length: 253.

string

Optional SOCKS5 username (RFC 1929), max 255 bytes. Maximum length: 255.

integer[]

Sandbox ports that serve HTTPS rather than plaintext HTTP. Affects how the proxy reaches the service inside the sandbox; the public URL is HTTPS either way. Certificates are not verified, so self-signed ones work. The envd port (49983) cannot be listed. Maximum items: 128.

string

Specify host mask which will be used for all sandbox requests

object

Per-domain transform rules applied to matching outbound HTTPS requests. Keys may be exact DNS names (for example, “api.example.com”) or a leading wildcard (for example, “.example.com”), and are normalized to lowercase on write. Wildcards match subdomains at any depth but not the apex domain; a bare "" is invalid. Exact rules take precedence, followed by the longest matching wildcard suffix, and matching rule sets are not merged. Broad wildcards such as “*.com” are allowed and may expose transformed credentials to every matching destination the sandbox contacts. Rules do not grant network access; configure allowOut separately to permit the destination. Additional keys accept object[] values.

Show Properties

object[]

Network rules attached to this named network policy; explicit network configuration is not supported by this deployment.

Show Properties

object

Transformations applied to matching egress requests before forwarding.

Show Properties

object

HTTP headers to inject or override in matching requests. An existing header with the same name is replaced. Values are plain strings; secret resolution happens client-side before sending to the API. Additional keys accept string values.

string

What the sandbox’s latest pause saved. full saved the filesystem and the memory, and resuming restores the sandbox where it left off. filesystem saved only the filesystem, and resuming reboots the sandbox from disk. Returned for a paused sandbox once its pause has finished, and omitted while it is still pausing. Allowed values: "full", "filesystem".

string | null

Time the machine last paused as an RFC 3339 timestamp, or null when it has not paused. May be null.

string

required

Identifier of the sandbox

string

required

Time when the sandbox was started Format: date-time.

string

required

State of the sandbox Allowed values: "running", "paused".

string

required

Identifier of the template from which is the sandbox created

object[]

At most one retained volume mounted at /data or /mnt/<name>.

Show Properties

string

required

Name of the volume

string

required

Path of the volume

string | null

Reason for the last wake or lifecycle transition, or null when none is recorded. May be null.

object[]

Lifecycle or credit grace warnings attached to this machine. Additional keys accept any values.

object

Checkpoint durability and recovery state.

Show Properties

string

required

Durability mode. Allowed values: "host_local", "bounded_checkpoint".

boolean

Whether a remote checkpoint is available in host-local mode.

integer

Configured checkpoint interval in seconds.

integer | null

Last committed checkpoint in Unix milliseconds. May be null.

integer | null

Age of the last checkpoint in milliseconds. May be null.

boolean

Whether machine execution was lost.

boolean

Whether a committed checkpoint can be recovered.

string

Checkpoint state. Allowed values: "degraded", "initializing", "committed".

string

Human-readable checkpoint status.

object

Preserved or lost source recovery state.

Show Properties

string

required

Recovery state. Allowed values: "preserved", "lost".

string

Recovery operation UUID when available.

string

required

Who funds the preserved source.

boolean

Whether the capture has recovered.

string

Machine recovery error identifier, including machine_lost.

boolean

Whether the execution state is terminal.

string

required

Explanation of the recovery state.

string

required

Recommended recovery action.

Errors

Status	Meaning
401	Authentication credential is missing or rejected.
403	The credential lacks the required scope.
404	The requested resource does not exist or is outside your organization.
429	Request or resource admission limit exceeded (`admission_limit`). Follow limit.next_action and Retry-After when present.
503	Service or persistence is temporarily unavailable.

curl --request GET \
  --url "https://api.bead.run/sandboxes/$SANDBOX_ID" \
  --header "X-API-Key: $BEAD_API_KEY"

{
  "alias": "<string>",
  "allowInternetAccess": {},
  "clientID": "<string>",
  "cpuCount": 123,
  "diskSizeMB": 123,
  "domain": {},
  "endAt": {},
  "envdAccessToken": "<string>",
  "envdUnresponsiveAtPause": true,
  "envdVersion": "<string>",
  "grace_deadline": {},
  "idle_timeout": {},
  "kind": "<string>",
  "last_activity": {},
  "lifecycle": {
    "autoResume": true,
    "onTimeout": "<string>"
  },
  "machine_state": "<string>",
  "memoryMB": 123,
  "metadata": {},
  "network": {
    "allowOut": [
      "<string>"
    ],
    "allowPublicTraffic": {},
    "denyOut": [
      "<string>"
    ],
    "dnsServers": [
      "<string>"
    ],
    "egressProxy": {
      "address": "<string>",
      "password": "<string>",
      "tls": {
        "caCert": "<string>",
        "enabled": true,
        "serverName": "<string>"
      },
      "username": "<string>"
    },
    "httpsPorts": [
      123
    ],
    "maskRequestHost": "<string>",
    "rules": {
      "<key>": [
        {
          "transform": {
            "headers": {}
          }
        }
      ]
    }
  },
  "pauseMode": "<string>",
  "paused_at": {},
  "sandboxID": "<string>",
  "startedAt": "<string>",
  "state": "<string>",
  "templateID": "<string>",
  "volumeMounts": [
    {
      "name": "<string>",
      "path": "<string>"
    }
  ],
  "wake_reason": {},
  "warnings": [
    {}
  ],
  "durability": {
    "mode": "<string>",
    "remoteCheckpoint": true,
    "checkpointIntervalSeconds": 123,
    "lastCommittedCheckpointAtMs": {},
    "checkpointAgeMs": {},
    "hostLost": true,
    "recoverable": true,
    "status": "<string>",
    "message": "<string>"
  },
  "preservation": {
    "status": "<string>",
    "operationID": "<string>",
    "billing": "<string>",
    "recovered": true,
    "code": "<string>",
    "terminal": true,
    "message": "<string>",
    "nextAction": "<string>"
  }
}

Start here

Endpoints

Get machine details

Authentication

Parameters

Response

200

Errors

​Authentication

​Parameters

​Response

​200

​Errors

Authentication

Parameters

Response

200

Errors