Skip to main content
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. With the TypeScript SDK, call vms.fork(). See TypeScript SDK reference.

Write the code that forks a sandbox.

Before you start

Fork a sandbox

In the app, open the sandbox on the Sandboxes page and choose Fork. See Fork a sandbox in the app. With the API, send POST /v1/sandboxes with fromSandbox, the ID of the source sandbox:
The API answers 202 with the new sandbox and its create operation. forkedFrom holds the ID of the source:
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. A fork is a start: the start limits and the sizes of your plan apply. See Plans and limits.

What a fork gets

A fork gets the saved files of the source. See Saved files for the folders that a snapshot saves. The processes and the memory of the source do not come to the fork. 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:
The answer is the first fork. Its batch field holds each fork of the request, in creation order:
  • 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

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.