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

# Create, get, and delete a sandbox

> Create a sandbox with the REST API, wait until it is running, and delete it.

Create a sandbox with one API call. Read the sandbox until its state is `running`. Delete it when you do not need it.

Write the code that creates and deletes a sandbox.

Use POST /v1/sandboxes with an Idempotency-Key to create a sandbox.
Read GET /v1/sandboxes/{id} until the state is running.
Retry after retryAfterSeconds when the API answers no\_capacity.
Delete the sandbox with DELETE /v1/sandboxes/{id}.
Do not ask me to share my API key.

## Before you start

* Your workspace needs a plan or a trial. See [Choose a plan or start a trial](https://vms.dev/docs/workspace/billing.md).
* You need an API key with the `sandboxes:write` scope. A key with only `sandboxes:read` can read sandboxes and operations, but it cannot create or delete them. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* The examples use TypeScript with `fetch`. You can also use `curl`.

## Create a sandbox

Send `POST /v1/sandboxes` with a `size`: `small`, `medium`, `large`, or `xlarge`. See the [sizes](https://vms.dev/docs/reference/plans.md#sandbox-sizes). To make a sandbox from the files of another sandbox, see [Fork a sandbox](https://vms.dev/docs/sandboxes/fork.md).

```typescript TypeScript theme={null}
const headers = {
  Authorization: `Bearer ${process.env.VMS_API_KEY}`,
  "Content-Type": "application/json",
  "Idempotency-Key": crypto.randomUUID(),
};

const response = await fetch("https://vms.dev/api/v1/sandboxes", {
  method: "POST",
  headers,
  body: JSON.stringify({ size: "small" }),
});

const sandbox = await response.json();

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

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

The API answers `202` with the sandbox in the `creating` state. The `operation` field holds the create operation:

```json theme={null}
{
  "id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "name": null,
  "state": "creating",
  "size": "small",
  "health": null,
  "operation": {
    "id": "op_06d8k3m7q2v9x4b1n5c0e8f2jb",
    "sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
    "kind": "create",
    "status": "pending",
    "error": null,
    "createdAt": "2026-11-16T02:10:00.000Z",
    "updatedAt": "2026-11-16T02:10:00.000Z",
    "completedAt": null
  },
  "createdAt": "2026-11-16T02:10:00.000Z",
  "updatedAt": "2026-11-16T02:10:00.000Z"
}
```

The full object has more fields. See [`GET /v1/sandboxes/{id}`](https://vms.dev/docs/api-reference/sandboxes/get-a-sandbox).

### Give environment variables and files

Send `env` and `files` in the create body, so that the sandbox is ready for your agent when it is `running`:

```json theme={null}
{
  "size": "small",
  "env": { "OPENAI_API_KEY": "sk-...", "NODE_ENV": "production" },
  "files": [
    { "path": "/home/user/.npmrc", "content": "registry=https://registry.npmjs.org/\n" },
    { "path": "/home/user/run.sh", "content": "IyEvYmluL3NoCmVjaG8gaGkK", "encoding": "base64", "mode": "0755" }
  ]
}
```

* `env` has up to 100 variables. Each command, shell, and SSH session gets them. A name has letters, digits, and `_`, and does not start with a digit. A value has up to 4096 characters.
* `files` has up to 20 files, with up to 65,536 characters of content in total. A `path` is absolute. `encoding` is `utf8` (the default) or `base64`. A file in `/home/user` belongs to `user`.
* The files are written one time, at the first start. A resume keeps your changes to them. The variables stay for each start.

To start with the files of a prepared sandbox, send `template`: the name or the ID of a template, or a share code from another workspace. See [Save a sandbox as a template](https://vms.dev/docs/sandboxes/templates.md).

* The API stores both encrypted and does not show them again.

### Send an Idempotency-Key

Send a new `Idempotency-Key` header, such as a UUID, with each create. If the network fails, send the same request with the same key again. Within 24 hours, the API returns the first result and does not create a second sandbox.

* The same key with a different body answers `409`.
* A create that answered `503 no_capacity` keeps no result. A retry with the same key tries again.

### When no host has room

A sandbox usually starts on a machine that is ready. If no ready machine is free but a host has room, the API still answers `202`, and the sandbox is `running` when the next machine of its size is ready, a few seconds later. After many starts of one size in a short time, more machines of that size stay ready for one hour. If no host has room for the size, the API answers `503` at once:

```json theme={null}
{
  "error": {
    "code": "no_capacity",
    "message": "No host has room for a sandbox of this size now. Try again later.",
    "requestId": "19283a6c-8864-483f-8dab-320eec5015e1",
    "retryAfterSeconds": 5,
    "sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2jc"
  }
}
```

Wait `retryAfterSeconds`, then try again or choose a different size. The `Retry-After` header has the same value. The sandbox in `sandboxId` is in the `failed` state. Its create operation has the error `no_capacity`.

If the hosts are full when the new machine must start, the sandbox moves to `failed` within 60 seconds, and its create operation fails with `no_capacity`.

### When a create is above a limit

The plan sets the sizes, the sandboxes at a time, and the starts each minute and each day. A create above a limit makes no sandbox:

* `402 billing_required`: the workspace has no plan and no trial, or a payment review is open.
* `403 size_not_allowed`: the trial does not include the size. Each paid plan includes each size.
* `429 start_limit`: too many sandboxes at a time, or too many starts. For too many starts, wait `retryAfterSeconds`, then try again.

Read your limits with `GET /v1/limits`. See [the limits of each plan](https://vms.dev/docs/reference/plans.md#limits).

### Answer within 1.5 seconds

Send `"failFast": true` in the body when your code cannot wait. The API then answers within 1.5 seconds. If it cannot answer in time, for example because a request with the same `Idempotency-Key` is still open, it answers `503 no_capacity` with `retryAfterSeconds`.

## Wait until the sandbox is running

The sandbox moves from `creating` to `starting`, then to `running`. Read it with `GET /v1/sandboxes/{id}` until the state is `running`. A key with `sandboxes:read` is enough.

```typescript TypeScript theme={null}
async function waitUntilRunning(id: string) {
  for (;;) {
    const response = await fetch(`https://vms.dev/api/v1/sandboxes/${id}`, {
      headers: { Authorization: `Bearer ${process.env.VMS_API_KEY}` },
    });
    const sandbox = await response.json();

    if (sandbox.state === "running") return sandbox;

    if (sandbox.state === "failed") throw new Error(sandbox.operation.error.message);

    await new Promise((resolve) => setTimeout(resolve, 500));
  }
}
```

```bash cURL theme={null}
curl https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja \
  -H "Authorization: Bearer $VMS_API_KEY"
```

To get a request when the sandbox is running, in place of reads, add a [webhook endpoint](https://vms.dev/docs/sandboxes/webhooks.md).

You can also read the operation with `GET /v1/operations/{id}`. Its `status` is `pending`, `running`, `succeeded`, or `failed`. A failed operation has an `error` with a `code` and a `message`.

> [!NOTE]
>
> Each API key can send 1,200 requests in one minute. Wait 1 second between two reads. After a `429`, wait for the seconds in `Retry-After`.

## Delete a sandbox

Send `DELETE /v1/sandboxes/{id}`. The API answers `202` with the sandbox in the `deleting` state and its delete operation. The sandbox then moves to `deleted`.

```typescript TypeScript theme={null}
const response = await fetch(`https://vms.dev/api/v1/sandboxes/${sandbox.id}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.VMS_API_KEY}` },
});

console.log(response.status, (await response.json()).state);
```

```bash cURL theme={null}
curl -X DELETE https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja \
  -H "Authorization: Bearer $VMS_API_KEY"
```

After the delete is complete, the next `GET` returns the sandbox one time with the state `deleted`. Each later `GET` answers `404`. A second `DELETE` while the sandbox is `deleting` returns the same sandbox.

When the delete is complete, `dataExpiresAt` shows the time of the delete. The saved files of the sandbox are deleted within 24 hours. Until then, you can [read the files of its snapshots](https://vms.dev/docs/sandboxes/snapshot-files.md#read-a-snapshot-of-a-deleted-sandbox). After that, you cannot get them back.

## Sandbox states

| State | Meaning |
| - | - |
| `creating` | The sandbox has a place on a host. |
| `starting` | The sandbox boots. |
| `running` | You can use the sandbox. |
| `stopping` | The sandbox saves its files before it stops. See [Stop and resume a sandbox](https://vms.dev/docs/sandboxes/stop-and-resume.md). |
| `stopped` | The sandbox is paused and not billed. Its files are saved. |
| `error` | The sandbox cannot run, for example because its host stopped or its saved files did not come back after a resume. `errorReason` tells why. You can resume it again. See [Health and recovery](https://vms.dev/docs/reference/health-and-recovery.md). |
| `deleting` | The sandbox and its data are being removed. |
| `deleted` | The sandbox is removed. Its saved files are deleted within 24 hours. |
| `failed` | The sandbox did not start, for example because no host had room. |

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


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