> ## 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.

# Agent fleet

> Create an agent fleet in a batch, poll results for large fleets, and inspect each machine before cleanup.

Create an agent fleet of independent machines, then run and clean up each machine yourself. Use a fleet when you need live machines rather than one automatically managed command per member.

## Create a fleet

```bash theme={null}
bead fleet --template base --size small --count 2 --kind temporary --timeout 300
```

The API is `POST /v2/sandboxes/fleet`:

```json theme={null}
{"count":2,"request":{"templateID":"base","size":"small","kind":"temporary","timeout":300}}
```

Count accepts 1–10000. Quota and prepaid funding for the entire batch are reserved before dispatch. Quota or funding refusal admits no members. Current capacity can still produce partial results.

## Read every result

For up to 256 members, the API returns synchronous HTTP 207 with ordered `results`. Each item has an index, status, and response. A successful member reports 201 only after guest readiness; a member that cannot fit can report a structured 429.

Do not treat batch submission as proof that every member is running. Retain each successful machine ID and inspect each error's next action.

## Poll larger batches

Counts above 256 without an attached credential profile return HTTP 202 with `fleetID` and `resultsURL`. Profile-bearing fleets use the synchronous result path. Poll the authenticated results URL until the members finish. Pending members report 202; successful ready members report 201. Dispatch continues after the original HTTP caller disconnects.

For example, if `resultsURL` is a relative API path:

```bash theme={null}
bead api GET /v2/sandboxes/fleets/FLEET_ID
```

## Retry and clean up

Retain the batch idempotency key before sending the request. Reuse it with an identical request after a lost reply; do not submit a fresh batch merely because the first response was uncertain.

Run work on each ready member through [exec](https://docs.bead.run/connect/exec.md) or [runner prompts](https://docs.bead.run/agents/runners.md). Delete each successful machine when finished:

```bash theme={null}
bead delete MACHINE_ID
```

[Private reachability](https://docs.bead.run/parallel/networking.md) depends on placement. Use [swarms](https://docs.bead.run/parallel/swarms.md) when you want command execution, result collection, and cleanup managed together.


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