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

# Parallel command execution

> Fan out work with parallel command execution, collect JSONL results, and cancel or retry sandbox tasks deliberately.

Distribute work with parallel command execution to fan out one command over a count or a list of JSON inputs. The swarm controller creates temporary machines, collects bounded results, and deletes the machines.

## Start a swarm

```bash theme={null}
bead swarm run 'printf "%s\n" "$BEAD_SWARM_INPUT"' --count 2 --concurrency 2
```

Commands run under `/bin/sh -c` in `/root`. For code tasks, select a prepared template or snapshot, or clone a public repository inside the command.

The API is `POST /swarms`. Supply an idempotency key and exactly one of `count` or `inputs`:

```json theme={null}
{
  "template":"python",
  "command":"python3 -c 'import os; print(os.environ[\"BEAD_SWARM_INPUT\"])'",
  "inputs":[{"seed":1},{"seed":2}],
  "concurrency":2,
  "time_limit_seconds":300,
  "retries":0
}
```

Each process receives JSON in `BEAD_SWARM_INPUT`, its zero-based index in `BEAD_SWARM_INDEX`, and zero-based attempt in `BEAD_SWARM_ATTEMPT`. A count supplies JSON `null` inputs.

## Poll and collect

```bash theme={null}
bead swarm status JOB
bead swarm results JOB --output results.jsonl
```

Status is `queued`, `running`, `completed`, `failed`, or `cancelled`. Results are available after terminal state; the results route returns 409 while running. Check every member's exit code and error details. A null exit code means no confirmed command exit.

Results expire 24 hours after completion. Each stdout/stderr stream retains at most 64 KiB and includes encoding and truncation information. Optional `output_files` globs collect at most 16 files and 32 KiB total. Files use base64 bytes; collection errors do not replace the command exit code.

## Bounds and retries

There are at most 256 total possible attempts, with 0–3 retries, concurrency 1–256, and a 1–3600-second member limit. Commands and each serialized input are limited to 16 KiB. All possible attempts are admitted and funded up front. Waiting for capacity consumes the job deadline.

Retries can repeat external effects. An uncertain command is not silently replayed; a fresh attempt is possible only when you allowed retries.

## Cancel

```bash theme={null}
bead swarm cancel JOB
```

Cancellation is asynchronous. Poll until terminal cleanup completes. Register `swarm.completed` through [webhooks](https://docs.bead.run/platform/webhooks.md) for a terminal notification and results URL.


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