Create a machine

POST

sandboxes

curl --request POST \
  --url "https://api.bead.run/v2/sandboxes" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "templateID": "python",
  "size": "small",
  "kind": "temporary",
  "timeout": 300,
  "envVars": {
    "APP_ENV": "development"
  }
}
JSON

from beadrun import Sandbox

sandbox = Sandbox.create(template="python", size="small", timeout=300)

import { Sandbox } from "@beadrun/sdk";

const sandbox = await Sandbox.create({ template: "python", size: "small", timeout: 300 });

{
  "alias": "<string>",
  "clientID": "<string>",
  "domain": {},
  "envdAccessToken": "<string>",
  "envdVersion": "<string>",
  "grace_deadline": {},
  "idle_timeout": {},
  "kind": "<string>",
  "last_activity": {},
  "machine_state": "<string>",
  "paused_at": {},
  "sandboxID": "<string>",
  "templateID": "<string>",
  "trafficAccessToken": {},
  "wake_reason": {},
  "warnings": [
    {}
  ]
}

Authentication

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

Parameters

string

Caller-generated durable retry key: lowercase ASCII letters, digits, and hyphens only. Reuse the same key and body after a connection failure. Minimum length: 1. Maximum length: 255.

Request body

The JSON body is required.

boolean

Internet access switch; false is rejected with 501 unsupported_feature.

boolean

default:false

Select persistent lifetime behavior with automatic pause; cannot be combined with explicit kind temporary.

boolean

default:true

Memory preservation for automatic pause; false is rejected with 501 unsupported_feature.

object

Auto-resume configuration for paused sandboxes.

Show Properties

boolean

default:false

required

Auto-resume enabled flag for paused sandboxes. Default false.

integer

Requested CPU count; dimensions round up to the smallest supported size. Must be positive and agree with an explicit size.

object

Environment variables installed in the machine; names cannot be empty or contain = or NUL, and values cannot contain NUL. Additional keys accept string values.

object

Workload identity configuration; explicit values are rejected with 501 unsupported_feature.

Show Properties

object

Named workload-token definitions, keyed by a caller-chosen token name. Additional keys accept object values.

Show Properties

object

Workload token configuration for this named token.

Show Properties

string

required

Audience of the workload token, stored exactly as provided.

string

required

Workload token type.

integer | string

default:900

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. Accepts integer or string (“never”).

string

Machine lifetime. Omission uses the template default; autoPause true or idle_timeout selects persistent behavior. Explicit temporary with autoPause true is rejected. Allowed values: "temporary", "persistent".

object | null

MCP configuration; non-null values are rejected with 501 unsupported_feature. May be null.

integer

Requested memory in MiB; dimensions round up to the smallest supported size. Must be positive and agree with an explicit size.

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

default:"medium"

Machine size; defaults to medium when neither size nor CPU/memory dimensions are supplied. Allowed values: "xs", "small", "medium", "large", "xlarge".

string

required

Published template or ready snapshot ID returned by the template catalog.

integer

default:300

Funded execution timeout in seconds. Temporary machines expire at this deadline; persistent machines keep their state and require funded execution windows. Format: int32. Minimum: 1. Maximum: 86400.

object[]

At most one retained volume mounted at /data or /mnt/<name>. Maximum items: 1.

Show Properties

string

required

Name of the volume

string

required

Path of the volume

curl --request POST \
  --url "https://api.bead.run/v2/sandboxes" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "templateID": "python",
  "size": "small",
  "kind": "temporary",
  "timeout": 300,
  "envVars": {
    "APP_ENV": "development"
  }
}
JSON

from beadrun import Sandbox

sandbox = Sandbox.create(template="python", size="small", timeout=300)

import { Sandbox } from "@beadrun/sdk";

const sandbox = await Sandbox.create({ template: "python", size: "small", timeout: 300 });

Response

201

The sandbox was created successfully.

string

Alias of the template

string

required

deprecated

Identifier of the client

string | null

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

string

Access token used for envd communication

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.

string

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

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

Identifier of the template from which is the sandbox created

string | null

Token required for accessing sandbox via proxy. May be null.

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.

Errors

Status	Meaning
400	Invalid request values, unsupported bounds, or malformed JSON.
401	Authentication credential is missing or rejected.
402	Insufficient prepaid credit (`insufficient_credit`) for the requested execution window.
403	The credential lacks the required scope.
404	The requested template or credential profile does not exist or is inaccessible.
409	Ownership/state conflict or request is already active (`idempotency_in_progress`, `idempotency_request_mismatch`). An expired execution attempt returns `execution_expired`.
413	Request body exceeds the route limit.
422	The prior operation outcome is unknown (`idempotency_outcome_unknown`), or the JSON body does not match the request contract.
429	Request or resource admission limit exceeded (`admission_limit`; trial capacity can return `free_capacity_full`). Follow limit.next_action and Retry-After when present.
500	Machine operation failed (`execution_failed`), or a capture was preserved for recovery (`snapshot_preserved`). Inspect the machine before issuing another operation.
501	This request selects a feature this deployment does not support (`unsupported_feature`).
502	Agent or credential setup failed after creation; the machine may exist. Inspect it before retrying.
503	Service or persistence is temporarily unavailable.
504	Machine acknowledgement deadline exceeded; inspect state before retrying the same request key.

curl --request POST \
  --url "https://api.bead.run/v2/sandboxes" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "templateID": "python",
  "size": "small",
  "kind": "temporary",
  "timeout": 300,
  "envVars": {
    "APP_ENV": "development"
  }
}
JSON

from beadrun import Sandbox

sandbox = Sandbox.create(template="python", size="small", timeout=300)

import { Sandbox } from "@beadrun/sdk";

const sandbox = await Sandbox.create({ template: "python", size: "small", timeout: 300 });

{
  "alias": "<string>",
  "clientID": "<string>",
  "domain": {},
  "envdAccessToken": "<string>",
  "envdVersion": "<string>",
  "grace_deadline": {},
  "idle_timeout": {},
  "kind": "<string>",
  "last_activity": {},
  "machine_state": "<string>",
  "paused_at": {},
  "sandboxID": "<string>",
  "templateID": "<string>",
  "trafficAccessToken": {},
  "wake_reason": {},
  "warnings": [
    {}
  ]
}

Start here

Endpoints

Create a machine

Authentication

Parameters

Request body

Response

201

Errors

​Authentication

​Parameters

​Request body

​Response

​201

​Errors

Authentication

Parameters

Request body

Response

201

Errors