Write the code that stops and resumes 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.
Stop a sandbox
SendPATCH /v1/sandboxes/{id} with "state": "stopped":
202 with the sandbox in the stopping state. The operation field holds the stop operation:
- It runs your pre-stop script, if the sandbox has one. See Run a script before the stop.
- It takes a last snapshot of the changed files. See Saved files.
- It pauses the sandbox. The host keeps its memory for 10 minutes.
stopped, and the operation is succeeded. Read the operation with GET /v1/operations/{id}, or the sandbox with GET /v1/sandboxes/{id}. A key with sandboxes:read is enough.
A sandbox also stops on its own at its stopAt, by default 1 hour after its start. See Stop a sandbox on its own.
A stop while a stop is pending returns the pending operation. A stop of a stopped sandbox returns the sandbox with its last stop operation. A stop of a creating or starting sandbox answers 409 sandbox_starting.
While the sandbox is stopping, a command or a file request answers 409 sandbox_stopping. When the sandbox is stopped, it answers 409 sandbox_not_running.
Run a script before the stop
Put an executable script at~/.vms/pre-stop of the user user, which is /home/user/.vms/pre-stop. Each stop runs it before the last snapshot, so the snapshot has the files that the script writes. Use it to save the work of your app, for example to write a cache to disk.
- The script runs as
user, in/home/user. A script without the executable bit runs withsh. - The script has 60 seconds. After 60 seconds, the script stops, and the stop continues.
- The stop continues also when the script exits with an error.
Resume a sandbox
SendPATCH /v1/sandboxes/{id} with "state": "running":
202 with the sandbox in the starting state and its resume operation. When the operation is succeeded, the sandbox is running.
- Within 10 minutes of the stop, the sandbox is
runningagain in less than 0.5 seconds. It has the same memory, so each process that ran before the stop still runs. - After 10 minutes, the host can use the memory for other sandboxes. When the host needs memory, it can end the hold earlier. Then the resume starts the sandbox on any host with room and puts back its saved files. See Resume from the saved files.
- A resume is a start. The start limits and the sizes of your plan apply. See Plans and limits.
- A resume of a
stoppingsandbox answers409 sandbox_stopping. Wait until it isstopped. - A resume of a
runningorstartingsandbox changes nothing. - You can also resume a sandbox in the
errorstate. It starts from its saved files.
Resume from the saved files
A resume after the hold starts the sandbox on a host with room, and puts back the files of its last snapshot. See Saved files for the folders that a snapshot saves.- The sandbox is
runningwhen its changes to the system folders are back and each file of the home folders shows. The time does not grow with the size of the home folders. - A file in a home folder that is not on the local disk yet downloads when a program opens it. The sandbox downloads the other files in the background. Then
hydratedistrue, and thesandbox.hydratedwebhook goes out. See Hydration. - The files that programs opened first after the last start download before the other files, up to 20,000 files. The sandbox saves this list with its next snapshot.
- The sandbox gets back its home folders, its folders at
/, its changes to the system folders, and its Docker volumes, containers, and tagged images. A container does not run until you start it, unless it has a restart policy. - Docker comes back a few seconds after the sandbox is
running. Then the services that you enabled withsystemctl enablestart. - The extended attributes of each file and the modification time of each folder are back when
hydratedistrue. - If the sandbox reboots before
hydratedistrue, the download continues after the boot. If the download stops, the sandbox tries it again 5 times. If it still cannot download the files,hydration.phaseisfailed, and thesandbox.degradedwebhook goes out with the reasonhydration_failed. The files that did not download are not in the home folders. Resume the sandbox from a stop to try again. - The processes and the memory do not come back. The sandbox boots again.
git statusin a Git repository in a home folder shows no false changes. The sandbox updates the index of each repository when each file is on the local disk.- The sandbox can get a new
ipv6address. Its name, its URLs, its SSH keys, and its SSH host key stay the same. - If no host has room, the API answers
503 no_capacitywithretryAfterSeconds. The sandbox staysstopped. Try again later.
error, with errorReason set to restore_failed. The resume operation is failed, with the code restore_failed. The saved files do not change. Resume the sandbox again.
Hydration
GET /v1/sandboxes/{id} shows how much of the restore is done:
A sandbox that starts from a template shows the same fields. To wait until each file is local, wait for the
sandbox.hydrated webhook. See Webhook events.
Change the size at resume
Sendsize with "state": "running" to resume a stopped sandbox with a different size:
sizewithout"state": "running"answers400.- A new
sizefor arunningorstartingsandbox answers409. Stop the sandbox first.
Base image upgrades
The base image is the operating system and the preinstalled tools of a sandbox.GET /v1/sandboxes/{id} shows its version in imageVersion. In the sandbox, /etc/vms-release shows the version of the image that the sandbox started from.
- A resume after the hold starts the sandbox on the latest base image. The resume puts back your saved files and your changes to the system folders on the new image. See Saved files.
- If you changed a file that the new image also changed, the sandbox keeps your version. The restore writes a line with the path of each such file to the system journal. Run
sudo journalctl --merge --grep "saved version"in the sandbox to read these lines. - A file that you changed and that the new image did not change stays as you left it.
- If you install or remove packages with
aptordpkg, the sandbox keeps its base image: the next snapshot setspinImagetotrue, because the package list of the old image does not match the new image. Send"pinImage": falseto move to the latest image. Then install your packages again if the new image does not have them. - A resume within 10 minutes of the stop keeps the base image, because the sandbox continues with its memory.
- A fork and a sandbox from a template start on the latest base image. A recovery after a host failure starts on the latest base image, unless the sandbox is pinned.
Keep the current base image
Send"pinImage": true to keep the current base image at each resume:
- You can send
pinImagein any state, also with"state": "running". - A pinned resume can take a few seconds more, because the host can start a new machine with the old image.
- If no host has the pinned image, the resume operation is
failedwith the codeimage_unavailable, and the sandbox staysstopped. Send"pinImage": false, and resume the sandbox again. - Send
"pinImage": falseto move the sandbox to the latest base image at its next resume after the hold. - A recovery after a host failure uses the pinned image if a host with room has it. If no host with room has it, the recovery starts on the latest base image, so that the sandbox runs again.
pinImagestaystrue. See Automatic recovery.
How long a stopped sandbox keeps its files
A stopped sandbox keeps its saved files for 30 days after the stop.GET /v1/sandboxes/{id} shows the date in dataExpiresAt:
- A resume sets
dataExpiresAttonull. The next stop sets a new date. - After
dataExpiresAt, a resume answers409 snapshot_expired. The sandbox staysstopped. Delete it, and create a new sandbox. - The saved files are deleted within 24 hours after
dataExpiresAt. You cannot get them back. - A sandbox in the
errororfailedstate also keeps its files for 30 days.
When the last snapshot fails
A stop must save the files of the sandbox. If the last snapshot fails 3 times:-
The operation is
failing. The code inerrorgives the cause: -
The sandbox is
runningagain, and you can use it. - The stop tries again each 5 minutes. A stop request in this time returns the same operation.
failed, with the code stop_cancelled.
When the stop gives up, it uses the last good snapshot. The sandbox is stopped, and the operation is succeeded with the same code in error. The owners and the admins of the workspace get an email. Changes after the last good snapshot are not saved.
Stop or resume many sandboxes
SendPOST /v1/sandboxes/update-many with items, a list of 1 to 500 changes. Each item has the id of a sandbox and the fields of an update:
200 with a result for each item, as create-many and delete-many do.