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

# VM fork

> Create a VM fork with independent copies of a running machine's files and memory, then poll the ordered results.

Choose a VM fork when several tasks need to branch from the same prepared process state. The source keeps running after capture resumes it.

## Create children

Trial accounts cannot fork. Add paid credit before creating fork children.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead --idempotency-key UUID sandbox fork ID --count 2 --timeout 300
```

Fork accepts 1–20 children. The API is `POST /sandboxes/{id}/fork` with `count` and `timeout`. It returns 202 with an `operationID`, a snapshot ID, and ordered pending child results.

Generate the idempotency UUID before dispatch and reuse it with the identical request after a lost response; a fresh CLI invocation without that UUID can create another batch.

`timeout` defaults to 300 seconds and accepts 1–86400 seconds. The funded lifetime includes capture waiting and does not restart when a child becomes ready.

## Poll the job

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead sandbox fork-get JOB
```

Keep the returned job ID. Inspect every child result and verify `memoryRestored: true` for each successful child. Capture happens once; child results stay in request order. The source continues running after capture resumes it.

## State and identity

Sources with an attached persistent [volume](https://docs.bead.run/platform/volumes.md) cannot fork; close files and mappings, then detach the volume first.

Children inherit the source's actual CPU and memory size and machine kind. Each successful child has independent writable state and a new platform identity.

Open connections break. Applications must reconnect external peers, and listeners bound to the old private address may need to rebind. Tenant secrets already in process memory can be inherited.

Fork does not inherit saved credential profiles; `inheritCredentials: true` is rejected. Use an explicitly consented [snapshot](https://docs.bead.run/snapshots/overview.md) when credential-profile inheritance is required. Children receive no desktop watch grants or human-control lease.

## Handle partial results

Admission and readiness are separate. Some children can succeed while others fail. Keep every successful child ID, inspect failures, and avoid treating a missing acknowledgement as proof that no machine exists.

Delete all successful children and the source when your work is complete:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead delete CHILD_ID
bead delete ID
```

For independent fresh machines use [fleets](https://docs.bead.run/parallel/fleets.md). For automatically cleaned-up commands use [swarms](https://docs.bead.run/parallel/swarms.md).


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