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

# Fork a sandbox

> Make one or more new sandboxes from the files and the environment variables of a running or stopped sandbox.

A fork is a new sandbox with the files of another sandbox. Prepare one sandbox, then fork it to give each of your agents a copy of the same state.

With the CLI, run `vms fork <name>`. See [CLI reference](https://vms.dev/docs/reference/cli.md#fork). With the TypeScript SDK, call `vms.fork()`. See [TypeScript SDK reference](https://vms.dev/docs/reference/typescript-sdk.md#fork).

Write the code that forks a sandbox.

Fork a sandbox with POST /v1/sandboxes and fromSandbox set to the ID of the source sandbox in the JSON body.
Read GET /v1/sandboxes/{id} with the ID of the fork until its state is running.
To make many forks, send count, and read the forks from the batch field of the response.
If the response is an error, show me its code and message.
Do not ask me to share my API key.

## Before you start

* You need an API key with the `sandboxes:write` scope. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* Read [Create, get, and delete a sandbox](https://vms.dev/docs/sandboxes/create-and-delete.md) first.
* The source sandbox must be `running` or `stopped`.

## Fork a sandbox

In the app, open the sandbox on the **Sandboxes** page and choose **Fork**. See [Fork a sandbox in the app](https://vms.dev/docs/sandboxes/in-the-app.md#fork-a-sandbox).

With the API, send `POST /v1/sandboxes` with `fromSandbox`, the ID of the source sandbox:

```typescript TypeScript theme={null}
const response = await fetch("https://vms.dev/api/v1/sandboxes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VMS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ fromSandbox: source.id, name: "agent-43" }),
});

const fork = await response.json();

console.log(response.status, fork.id, fork.forkedFrom);
```

```bash cURL theme={null}
curl https://vms.dev/api/v1/sandboxes \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fromSandbox": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja", "name": "agent-43"}'
```

The API answers `202` with the new sandbox and its `create` operation. `forkedFrom` holds the ID of the source:

```json theme={null}
{
  "id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2jd",
  "name": "agent-43",
  "state": "creating",
  "size": "medium",
  "forkedFrom": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "operation": {
    "id": "op_06d8k3m7q2v9x4b1n5c0e8f2je",
    "sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2jd",
    "kind": "create",
    "status": "pending",
    "error": null,
    "createdAt": "2026-11-16T09:30:00.000Z",
    "updatedAt": "2026-11-16T09:30:00.000Z",
    "completedAt": null
  }
}
```

The fork moves through `creating` and `starting` to `running`. It is `running` when its system files are in place. The files of the home folders then download in the background. See [Hydration](https://vms.dev/docs/sandboxes/stop-and-resume.md#hydration). A fork is a start: the start limits and the sizes of your plan apply. See [Plans and limits](https://vms.dev/docs/reference/plans.md).

## What a fork gets

A fork gets the saved files of the source. See [Saved files](https://vms.dev/docs/reference/saved-files.md) for the folders that a snapshot saves. The processes and the memory of the source do not come to the fork.

| A fork gets | A fork does not get |
| - | - |
| The saved files of the source | The name of the source. Send `name`, or the fork has no name. |
| The environment variables of the source | The auto-stop time of the source. The fork uses `stopAt` or `stopAfterSeconds` from the request, or the default of 1 hour. |
| The size of the source, if you do not send `size` | The URLs of the source |
| | The labels and the SSH keys of the source |

Each fork gets its own hostname, SSH host keys, IPv6 address, and guest agent key.

* Send `env` to add or change environment variables. A variable in `env` replaces the variable of the source with the same name.
* Send `size` to give the fork a different size. The size must be in your plan.

The fork and the source do not share changes. A change in the fork does not change the source, and a change in the source after the fork does not change the fork.

## Fork a running sandbox

When the source is `running`, the fork first takes a new snapshot of the source. So the fork has each file that the source wrote before your request. The source continues to run. The new snapshot adds its time to the start of the fork: about 1 second, and more when the source changed many files since its last snapshot.

Send `"freshSnapshot": false` to start the fork from the last snapshot of the source. The fork starts faster, but it does not have the changes after that snapshot. A running sandbox takes a snapshot about each minute. If the source has no snapshot yet, the fork takes a new snapshot.

When the source is `stopped`, the fork uses the last snapshot of the stop. `freshSnapshot` has no effect.

## Make many forks

Send `count`, from 1 to 100, to make more than one fork in one request:

```bash theme={null}
curl https://vms.dev/api/v1/sandboxes \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fromSandbox": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja", "count": 10}'
```

The answer is the first fork. Its `batch` field holds each fork of the request, in creation order:

```json theme={null}
{
  "id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2jd",
  "forkedFrom": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "batch": [
    { "id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2jd", "forkedFrom": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja" },
    { "id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2jf", "forkedFrom": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja" }
  ]
}
```

* The start limits count each fork. If one fork does not fit a limit, the API makes no fork.
* If no host has room for each fork, the API answers `503 no_capacity` and makes no fork. If a host has room but no ready machine is free, the forks start a few seconds later.
* Do not send `name` with a `count` of more than 1, because each sandbox needs a different name. The API answers `400`.

## Errors

| Status and code | Cause |
| - | - |
| `400` | You sent `count` or `freshSnapshot` without `fromSandbox`, `template` with `fromSandbox`, or `name` with a `count` of more than 1. |
| `404 not_found` | The workspace has no sandbox with the ID in `fromSandbox`, or the sandbox is deleted. |
| `409 sandbox_starting` | The source is `creating` or `starting`. Fork it when it is `running`. |
| `409 sandbox_stopping` | The source is `stopping`. Fork it when it is `stopped`. |
| `409 conflict` | The source is in the `error` or `failed` state. |
| `409 snapshot_expired` | The saved files of the source are deleted, 30 days after its stop. |
| `503 no_capacity` | No host has room for the fork. The body has `retryAfterSeconds`. |

If the fork cannot take the new snapshot of the source, or cannot put the files in place, the fork moves to `failed`. Its `create` operation is `failed`, with the code `fork_failed`. The source does not change. Fork it again.

## Saved files of a fork

A fork uses the saved files of the source. They stay while the fork needs them, also after you delete the source. A fork keeps its saved files for 30 days after its stop, as each sandbox does. See [How long a stopped sandbox keeps its files](https://vms.dev/docs/sandboxes/stop-and-resume.md#how-long-a-stopped-sandbox-keeps-its-files).

Read the [changelog.](https://vms.dev/docs/changelog.md)


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