Endpoints
Create a fleet
Create many machines from one request and inspect each member’s result.
POST
/
v2
/
sandboxes
/
fleet
curl --request POST \
--url "https://api.bead.run/v2/sandboxes/fleet" \
--header "X-API-Key: $BEAD_API_KEY" \
--header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
--header "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"count": 2,
"request": {
"templateID": "python",
"size": "small",
"timeout": 300
}
}
JSON
from beadrun import Fleet
fleet = Fleet.create(2, template="python", size="small", timeout=300)
import { Fleet } from "@beadrun/sdk";
const fleet = await Fleet.create(2, { template: "python", size: "small", timeout: 300 });
{
"fleetID": "<string>",
"status": "<string>",
"resultsURL": "<string>",
"results": [
{
"index": 123,
"status": 123,
"operationID": "<string>",
"response": {
"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": [
{}
],
"code": 123,
"message": "<string>",
"error_code": "<string>",
"limit": {
"limit": "<string>",
"maximum": 123,
"usage": 123,
"next_action": "<string>",
"reset_at": 123
},
"operationID": "<string>",
"status": "<string>"
}
}
]
}Authentication
Send your scoped bearer token in theAuthorization: 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: 240.Request body
The JSON body is required.integer
required
Number of machines in the fleet; account policy may impose a lower batch limit. Minimum:
1. Maximum: 10000.object
required
Sandbox creation request. All system communication with the sandbox is always secured; the template’s envd version must support secured access.
Show Properties
Show Properties
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
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
Show Properties
object
Named workload-token definitions, keyed by a caller-chosen token name. Additional keys accept
object values.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
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
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
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
Show Properties
object[]
Network rules attached to this named network policy; explicit network configuration is not supported by this deployment.
Show Properties
Show Properties
object
Transformations applied to matching egress requests before forwarding.
Show Properties
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.curl --request POST \
--url "https://api.bead.run/v2/sandboxes/fleet" \
--header "X-API-Key: $BEAD_API_KEY" \
--header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
--header "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"count": 2,
"request": {
"templateID": "python",
"size": "small",
"timeout": 300
}
}
JSON
from beadrun import Fleet
fleet = Fleet.create(2, template="python", size="small", timeout=300)
import { Fleet } from "@beadrun/sdk";
const fleet = await Fleet.create(2, { template: "python", size: "small", timeout: 300 });
Response
202
Large fleet accepted for asynchronous creation.string
required
Fleet UUID to poll.
string
required
Fleet creation is pending. Allowed values:
"pending".string
required
Relative URL to poll fleet results.
207
Ordered per-machine results; inspect each member status.object[]
required
One result per requested machine.
Show Properties
Show Properties
integer
required
Zero-based request index.
integer
required
HTTP status for this member; 202 means it is still pending.
string
Operation UUID for a pending member.
object
Machine connection fields on success, or an error body on failure. Accepts
object or object or object.Show Properties
Show Properties
string
Alias of the template
string
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
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
Identifier of the sandbox
string
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.integer
HTTP status code.
string
Explanation of the failed request.
string
Stable error identifier when supplied; use it to decide how to recover.
object
The resource limit that blocked the request.
string
Operation UUID.
string
Current operation state.
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. |
| 409 | Ownership/state conflict or request is already active (idempotency_in_progress, idempotency_request_mismatch). |
| 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. |
| 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. |
⌘I
curl --request POST \
--url "https://api.bead.run/v2/sandboxes/fleet" \
--header "X-API-Key: $BEAD_API_KEY" \
--header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
--header "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"count": 2,
"request": {
"templateID": "python",
"size": "small",
"timeout": 300
}
}
JSON
from beadrun import Fleet
fleet = Fleet.create(2, template="python", size="small", timeout=300)
import { Fleet } from "@beadrun/sdk";
const fleet = await Fleet.create(2, { template: "python", size: "small", timeout: 300 });
{
"fleetID": "<string>",
"status": "<string>",
"resultsURL": "<string>",
"results": [
{
"index": 123,
"status": 123,
"operationID": "<string>",
"response": {
"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": [
{}
],
"code": 123,
"message": "<string>",
"error_code": "<string>",
"limit": {
"limit": "<string>",
"maximum": 123,
"usage": 123,
"next_action": "<string>",
"reset_at": 123
},
"operationID": "<string>",
"status": "<string>"
}
}
]
}