> ## 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 a sandbox on its own

> Set the time when a sandbox stops on its own, extend it, or turn it off, so that a sandbox that you forget does not run up a bill.

Each sandbox stops on its own 1 hour after its start. Set a different time at create, extend it later, or turn it off.

Write the code that sets the auto-stop of a sandbox.

Create a sandbox with POST /v1/sandboxes and stopAfterSeconds set to 7200.
Read stopAt in the response.
Extend the auto-stop with PATCH /v1/sandboxes/{id} and stopAfterSeconds set to 14400.
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) and [Stop and resume a sandbox](https://vms.dev/docs/sandboxes/stop-and-resume.md) first.

## How the auto-stop works

Each sandbox has two fields:

| Field | Value |
| - | - |
| `stopAfterSeconds` | The seconds that the sandbox runs after each start. The default is `3600`, which is 1 hour. `null` when the auto-stop is off. |
| `stopAt` | The time of the next auto-stop. `null` when the auto-stop is off, or when the sandbox is not `creating`, `starting`, or `running`. |

At `stopAt`, the sandbox stops with a normal stop. The pre-stop script runs, the sandbox saves its files, and the host keeps its memory for 10 minutes. `GET /v1/sandboxes/{id}` shows the stop in `operation`, as for a stop that you send. See [Stop a sandbox](https://vms.dev/docs/sandboxes/stop-and-resume.md#stop-a-sandbox).

Each resume sets a new `stopAt`: the time of the resume plus `stopAfterSeconds`.

## Set the auto-stop at create

Send `stopAfterSeconds` with the create, from `60` to `2592000` (30 days):

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

const sandbox = await response.json();

console.log(sandbox.stopAt, sandbox.stopAfterSeconds);
```

```bash cURL theme={null}
curl https://vms.dev/api/v1/sandboxes \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size": "small", "stopAfterSeconds": 7200}'
```

The response shows the time in `stopAt`:

```json theme={null}
{
  "id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "state": "creating",
  "stopAt": "2026-11-16T11:30:00.000Z",
  "stopAfterSeconds": 7200
}
```

To give a time, send `stopAt` in place of `stopAfterSeconds`, for example `"stopAt": "2026-11-16T18:00:00Z"`. The time must be in the future and within 30 days. Do not send `stopAt` and `stopAfterSeconds` in one request. The API answers `400`.

## Extend the auto-stop

Send `PATCH /v1/sandboxes/{id}` with a new `stopAfterSeconds`:

```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({ stopAfterSeconds: 14400 }),
});

const updated = await response.json();

console.log(updated.stopAt);
```

```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 '{"stopAfterSeconds": 14400}'
```

The API answers `200` with the sandbox.

* The new time counts from the current start of the sandbox, not from the request. If the sandbox already ran for longer, it stops now.
* A `stopAt` in the `PATCH` body sets the time of the next auto-stop. You can send `stopAt` only when the sandbox is `creating`, `starting`, or `running`. For other states, the API answers `409`.
* A `stopAfterSeconds` for a `stopped` sandbox applies at the next resume.

## Turn off the auto-stop

Send `null` in `stopAfterSeconds` or in `stopAt`, at create or with `PATCH /v1/sandboxes/{id}`:

```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 '{"stopAfterSeconds": null}'
```

Then `stopAt` and `stopAfterSeconds` are `null`, and the sandbox runs until you stop it.

## Limits of the trial

In the trial, a sandbox stops on its own within 4 hours of its start. `autoStopSeconds` in [`GET /v1/limits`](https://vms.dev/docs/reference/plans#limits) shows this limit. A `stopAfterSeconds` above `14400`, a `stopAt` more than 4 hours after the start, and `null` answer `400`. Each paid plan has no limit. See [Trial](https://vms.dev/docs/reference/plans.md#trial).

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


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