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
- You need an API key with the
sandboxes:writescope. See API keys. - Read Create, get, and delete a sandbox first.
- The source sandbox must be
runningorstopped.
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, sendPOST /v1/sandboxes with fromSandbox, the ID of the source sandbox:
202 with the new sandbox and its create operation. forkedFrom holds the ID of the source:
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
envto add or change environment variables. A variable inenvreplaces the variable of the source with the same name. - Send
sizeto give the fork a different size. The size must be in your plan.
Fork a running sandbox
When the source isrunning, 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
Sendcount, from 1 to 100, to make more than one fork in one request:
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_capacityand makes no fork. If a host has room but no ready machine is free, the forks start a few seconds later. - Do not send
namewith acountof more than 1, because each sandbox needs a different name. The API answers400.
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.