> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a fleet

> Create many machines from one request and inspect each member’s result.

## Authentication

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

## Parameters

**Idempotency-Key** `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.

**count** `integer` *required*

Number of machines in the fleet; account policy may impose a lower batch limit. Minimum: `1`. Maximum: `10000`.

**request** `object` *required*

Sandbox creation request. All system communication with the sandbox is always secured; the template's envd version must support secured access.

**Properties**

**allow\_internet\_access** `boolean`

Internet access switch; false is rejected with 501 unsupported\_feature.

**autoPause** `boolean` (default: false)

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

**autoPauseMemory** `boolean` (default: true)

Memory preservation for automatic pause; false is rejected with 501 unsupported\_feature.

**autoResume** `object`

Auto-resume configuration for paused sandboxes.

**Properties**

**enabled** `boolean` *required* (default: false)

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

**cpuCount** `integer`

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

**envVars** `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.

**iam** `object`

Workload identity configuration; explicit values are rejected with 501 unsupported\_feature.

**Properties**

**tokens** `object`

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

**Properties**

**\<key>** `object`

Workload token configuration for this named token.

**Properties**

**audience** `string` *required*

Audience of the workload token, stored exactly as provided.

**tokenType** `string` *required*

Workload token type.

**idle\_timeout** `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").

**kind** `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"`.

**mcp** `object | null`

MCP configuration; non-null values are rejected with 501 unsupported\_feature. May be `null`.

**memoryMB** `integer`

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

**metadata** `object`

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

**network** `object`

Network configuration object. This deployment rejects an explicit network configuration with 501 unsupported\_feature.

**Properties**

**allowOut** `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.

**allowPublicTraffic** `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`.

**denyOut** `string[]`

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

**dnsServers** `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`.

**egressProxy** `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`.

**Properties**

**address** `string` *required*

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

**password** `string`

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

**tls** `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`.

**Properties**

**caCert** `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`.

**enabled** `boolean` *required*

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

**serverName** `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`.

**username** `string`

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

**httpsPorts** `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`.

**maskRequestHost** `string`

Specify host mask which will be used for all sandbox requests

**rules** `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.

**Properties**

**\<key>** `object[]`

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

**Properties**

**transform** `object`

Transformations applied to matching egress requests before forwarding.

**Properties**

**headers** `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.

**size** `string` (default: medium)

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

**templateID** `string` *required*

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

**timeout** `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`.

**volumeMounts** `object[]`

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

**Properties**

**name** `string` *required*

Name of the volume

**path** `string` *required*

Path of the volume

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
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
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
from beadrun import Fleet

fleet = Fleet.create(2, template="python", size="small", timeout=300)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
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.

**fleetID** `string` *required*

Fleet UUID to poll.

**status** `string` *required*

Fleet creation is pending. Allowed values: `"pending"`.

**resultsURL** `string` *required*

Relative URL to poll fleet results.

### 207

Ordered per-machine results; inspect each member status.

**results** `object[]` *required*

One result per requested machine.

**Properties**

**index** `integer` *required*

Zero-based request index.

**status** `integer` *required*

HTTP status for this member; 202 means it is still pending.

**operationID** `string`

Operation UUID for a pending member.

**response** `object`

Machine connection fields on success, or an error body on failure. Accepts `object` or `object` or `object`.

**Properties**

**alias** `string`

Alias of the template

**clientID** `string` *deprecated*

Identifier of the client

**domain** `string | null`

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

**envdAccessToken** `string`

Access token used for envd communication

**envdVersion** `string`

Version of the envd running in the sandbox

**grace\_deadline** `string | null`

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

**idle\_timeout** `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").

**kind** `string`

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

**last\_activity** `string | null`

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

**machine\_state** `string`

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

**paused\_at** `string | null`

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

**sandboxID** `string`

Identifier of the sandbox

**templateID** `string`

Identifier of the template from which is the sandbox created

**trafficAccessToken** `string | null`

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

**wake\_reason** `string | null`

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

**warnings** `object[]`

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

**code** `integer`

HTTP status code.

**message** `string`

Explanation of the failed request.

**error\_code** `string`

Stable error identifier when supplied; use it to decide how to recover.

**limit** `object`

The resource limit that blocked the request.

**Properties**

**limit** `string` *required*

Name of the exhausted resource.

**maximum** `integer` *required*

Allowed amount of this resource.

**usage** `integer` *required*

Current usage counted against the limit.

**next\_action** `string` *required*

Action you can take to proceed.

**reset\_at** `integer`

Unix time in seconds when this time window resets.

**operationID** `string`

Operation UUID.

**status** `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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.