Skip to main content
Stop a sandbox when your agent does not use it. Billing stops, and the sandbox keeps its files. Resume it within 10 minutes, and each process continues where it was. Resume it later, and it starts again with its saved files.

Write the code that stops and resumes a sandbox.

Before you start

Stop a sandbox

Send PATCH /v1/sandboxes/{id} with "state": "stopped":
The API answers 202 with the sandbox in the stopping state. The operation field holds the stop operation:
A stop does these steps:
  1. It runs your pre-stop script, if the sandbox has one. See Run a script before the stop.
  2. It takes a last snapshot of the changed files. See Saved files.
  3. It pauses the sandbox. The host keeps its memory for 10 minutes.
Then the sandbox is 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 with sh.
  • 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

Send PATCH /v1/sandboxes/{id} with "state": "running":
The API answers 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 running again 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 stopping sandbox answers 409 sandbox_stopping. Wait until it is stopped.
  • A resume of a running or starting sandbox changes nothing.
  • You can also resume a sandbox in the error state. 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 running when 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 hydrated is true, and the sandbox.hydrated webhook 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 with systemctl enable start.
  • The extended attributes of each file and the modification time of each folder are back when hydrated is true.
  • If the sandbox reboots before hydrated is true, 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.phase is failed, and the sandbox.degraded webhook goes out with the reason hydration_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 status in 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 ipv6 address. 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_capacity with retryAfterSeconds. The sandbox stays stopped. Try again later.
If the files do not come back, the sandbox moves to 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

Send size with "state": "running" to resume a stopped sandbox with a different size:
The sandbox resumes from its saved files with the new size, also within 10 minutes of the stop. Each process stops. The size must be in your plan.
  • size without "state": "running" answers 400.
  • A new size for a running or starting sandbox answers 409. 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 apt or dpkg, the sandbox keeps its base image: the next snapshot sets pinImage to true, because the package list of the old image does not match the new image. Send "pinImage": false to 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 pinImage in 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 failed with the code image_unavailable, and the sandbox stays stopped. Send "pinImage": false, and resume the sandbox again.
  • Send "pinImage": false to 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. pinImage stays true. 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 dataExpiresAt to null. The next stop sets a new date.
  • After dataExpiresAt, a resume answers 409 snapshot_expired. The sandbox stays stopped. 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 error or failed state 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 in error gives the cause:
  • The sandbox is running again, and you can use it.
  • The stop tries again each 5 minutes. A stop request in this time returns the same operation.
To cancel the stop, resume the sandbox. The operation is then 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

Send POST /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:
The API answers 200 with a result for each item, as create-many and delete-many do.