> ## 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.

# Stop and resume a sandbox

> Stop a sandbox to stop its billing and keep its files, run a script before the stop, and resume the sandbox later, with a new size if you want.

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.

Stop a sandbox with PATCH /v1/sandboxes/{id} and state set to stopped in the JSON body.
Read GET /v1/operations/{id} with the operation ID from the response until the status is succeeded.
Resume the sandbox with PATCH /v1/sandboxes/{id} and state set to running, and wait until the state is running.
If the operation is failing, show me its error 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.

## Stop a sandbox

Send `PATCH /v1/sandboxes/{id}` with `"state": "stopped"`:

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

const stopping = await response.json();

console.log(response.status, stopping.state, stopping.operation.id);
```

```bash cURL theme={null}
curl -X PATCH https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "stopped"}'
```

The API answers `202` with the sandbox in the `stopping` state. The `operation` field holds the stop operation:

```json theme={null}
{
  "id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "state": "stopping",
  "operation": {
    "id": "op_06d8k3m7q2v9x4b1n5c0e8f2jc",
    "sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
    "kind": "stop",
    "status": "pending",
    "error": null,
    "createdAt": "2026-11-16T09:30:00.000Z",
    "updatedAt": "2026-11-16T09:30:00.000Z",
    "completedAt": null
  }
}
```

A stop does these steps:

1. It runs your pre-stop script, if the sandbox has one. See [Run a script before the stop](#run-a-script-before-the-stop).
2. It takes a last snapshot of the changed files. See [Saved files](https://vms.dev/docs/reference/saved-files.md).
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](https://vms.dev/docs/sandboxes/auto-stop.md).

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.

```bash theme={null}
mkdir -p ~/.vms
cat > ~/.vms/pre-stop <<'EOF'
#!/bin/sh
curl -fsS -X POST http://localhost:3000/save
EOF
chmod +x ~/.vms/pre-stop
```

* 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"`:

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

const resuming = await response.json();

console.log(response.status, resuming.state, resuming.operation.kind);
```

```bash cURL theme={null}
curl -X PATCH https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"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](#resume-from-the-saved-files).
* A resume is a start. The start limits and the sizes of your plan apply. See [Plans and limits](https://vms.dev/docs/reference/plans.md).
* 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](https://vms.dev/docs/reference/saved-files.md) 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](#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:

| Field | Value |
| - | - |
| `hydrated` | `true` when each saved file is on the local disk. A sandbox that did not restore saved files is always `true`. |
| `hydratedAt` | When the last restore put each saved file on the local disk. `null` when the sandbox did not restore saved files. |
| `hydration.phase` | `folding` reads the snapshots, `system` puts back the system folders, `docker` puts back Docker and starts your services, `hydrating` downloads the files of the home folders, and `hydrated` is the end. `failed` means that the download stopped for good. The sandbox is `running` at `docker`, before `hydrating`. |
| `hydration.filesDone` | The files of the home folders that are on the local disk |
| `hydration.filesTotal` | The files of the home folders that the restore puts back |
| `hydration.errorCode` | `hydration_failed` when the phase is `failed`, else `null` |

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](https://vms.dev/docs/reference/webhook-events.md).

### Change the size at resume

Send `size` with `"state": "running"` to resume a stopped sandbox with a different size:

```bash theme={null}
curl -X PATCH https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "running", "size": "large"}'
```

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.

```json theme={null}
{
  "id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "state": "running",
  "imageVersion": "ubuntu-26.04-20261116130819",
  "pinImage": false
}
```

* 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](https://vms.dev/docs/reference/saved-files.md).
* 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:

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

const pinned = await response.json();

console.log(pinned.imageVersion, pinned.pinImage);
```

```bash cURL theme={null}
curl -X PATCH https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pinImage": true}'
```

* 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](https://vms.dev/docs/reference/health-and-recovery.md#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`:

```json theme={null}
{
  "id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "state": "stopped",
  "dataExpiresAt": "2026-12-16T09:30:00.000Z"
}
```

* 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:

  | Code | Cause | Billed while `failing` | The stop gives up after |
  | - | - | - | - |
  | `agent_unreachable` | The guest agent does not answer, for example because a firewall in the sandbox blocks port 7911. | Yes | 1 hour |
  | `snapshot_failed` | The files could not be saved for another cause. | No | 3 days |

* 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:

```bash theme={null}
curl https://vms.dev/api/v1/sandboxes/update-many \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja", "state": "stopped"}, {"id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2jb", "state": "stopped"}]}'
```

The API answers `200` with a result for each item, as [create-many and delete-many](https://vms.dev/docs/sandboxes/list-and-label.md#create-or-delete-many-sandboxes) do.

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


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