> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete a sandbox or snapshot

> Delete a sandbox, its snapshots or a saved snapshot for good, follow the deletion until the data is erased, and what a delete keeps.

A delete is permanent. You cannot resume, fork or get back a deleted sandbox. There is no list of deleted sandboxes.

> [!WARNING]
>
> **If you want to use the data later, stop the sandbox. Do not delete it.** A stopped sandbox costs nothing and keeps its disk for at least 14 days. Save a saved snapshot before day 14 to keep it longer. Read [Stop a sandbox](https://docs.boat.dev/snapshots/stop.md).

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
boat stop bx_f7k2q9hd            # keeps the data; `boat resume` brings it back
boat delete bx_f7k2q9hd          # erases the sandbox AND its snapshots, for good
```

## Delete a sandbox

A delete of a running sandbox stops it at once. It takes no last snapshot. Billing for the sandbox ends at the delete.

Every sandbox or snapshot delete needs the header `X-Ascii-Confirm-Delete`. Its value must be exactly the target id. If it is not, boat refuses the request with `409` and deletes nothing. The header keeps its old name. The CLI and the dashboard set it for you.

```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
boat delete bx_f7k2q9hd          # asks first, then follows the operation to completion
boat delete bx_f7k2q9hd --yes    # no prompt, for scripts
```

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl -sS -X DELETE "$BOAT_API_BASE/sandboxes/$BOAT_ID" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "X-Ascii-Confirm-Delete: $BOAT_ID"
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
const accepted = await sandbox.deleteSandbox({
  sandboxId: "bx_f7k2q9hd",
  xAsciiConfirmDelete: "bx_f7k2q9hd",
});
console.log(accepted.operation.id, accepted.operation.status);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
accepted = sandbox.delete_sandbox(
    x_ascii_confirm_delete="bx_f7k2q9hd",
    sandbox_id="bx_f7k2q9hd",
)
print(accepted.operation.id, accepted.operation.status)
```

`$BOAT_API_BASE` is `https://boat.dev/api/v1`.

In the dashboard, open [Sandboxes](https://boat.dev/dashboard?tab=sandboxes). Open the `⋯` menu on the row of the sandbox and choose **Delete permanently…**.

## How a delete works

1. You send a delete request.
2. boat returns `202 Accepted` with an operation.
3. The sandbox or snapshot disappears from lists, resumes and forks at once.
4. boat erases the stored data in the background, when nothing reads it any more.
5. You poll the operation until its status is `completed`.

boat never refuses a delete because the data is still in use.

The `stage` of the operation tells you where the deletion is.

| `stage` | Meaning |
| - | - |
| `removing` | boat erases the stored data now. |
| `waiting_for_uploads` | boat erases the data at `expectedBy`, when the last upload link for it expires. This is at most six hours after the last upload. |
| `retrying` | A short fault occurred. boat tries again by itself. |
| `completed` | boat erased every snapshot of it. A newer snapshot, a fork or a saved snapshot made from it keeps the data it reads. That data goes when you delete those too. |

> [!WARNING]
>
> You cannot cancel a deletion operation.

## Poll the operation

A delete returns an operation id (`bdop_…`). Poll it until `status` is `completed`.

```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
boat deletion status bdop_0123456789abcdef0123456789abcdef
```

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl -sS "$BOAT_API_BASE/deletion-operations/$OPERATION_ID" \
  -H "Authorization: Bearer $BOAT_API_KEY"
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
const current = await sandbox.getDeletionOperation({ operationId: accepted.operation.id });
console.log(current.operation.status);   // pending | processing | blocked | completed
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
current = sandbox.get_deletion_operation(accepted.operation.id)
print(current.operation.status)
```

`boat delete` already polls for you. It prints the operation when it finishes. Use `boat deletion status` to check later on an operation that you started elsewhere.

## Delete one snapshot

| Request | What it deletes | Confirmation header |
| - | - | - |
| `DELETE /snapshots/{snapshotId}` | One automatic snapshot | The snapshot id |
| `DELETE /sandboxes/{sandboxId}/snapshots` | Every automatic snapshot of one sandbox. The sandbox stays. A stopped sandbox with no snapshot has nothing to resume from. | The sandbox id |
| `DELETE /saved-snapshots/{name}` | One saved snapshot, by name | None |

```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
boat snapshot delete <snapshotId>               # one automatic snapshot
boat snapshot delete --all bx_f7k2q9hd          # every automatic snapshot of a sandbox
boat snapshot delete --all bx_f7k2q9hd --yes    # same, no prompt, for scripts
boat snapshot rm web-stack                      # a saved snapshot, by name
```

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl -sS -X DELETE "$BOAT_API_BASE/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "X-Ascii-Confirm-Delete: $SNAPSHOT_ID"

curl -sS -X DELETE "$BOAT_API_BASE/sandboxes/$BOAT_ID/snapshots" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "X-Ascii-Confirm-Delete: $BOAT_ID"

curl -sS -X DELETE "$BOAT_API_BASE/saved-snapshots/web-stack" \
  -H "Authorization: Bearer $BOAT_API_KEY"
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
await sandbox.deleteSnapshot({
  snapshotId: "<snapshotId>",
  xAsciiConfirmDelete: "<snapshotId>",
});

await sandbox.deleteSandboxSnapshots({
  sandboxId: "bx_f7k2q9hd",
  xAsciiConfirmDelete: "bx_f7k2q9hd",
});

await sandbox.deleteSavedSnapshot({ name: "web-stack" });
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
sandbox.delete_snapshot(
    snapshot_id="<snapshotId>",
    x_ascii_confirm_delete="<snapshotId>",
)

sandbox.delete_sandbox_snapshots(
    sandbox_id="bx_f7k2q9hd",
    x_ascii_confirm_delete="bx_f7k2q9hd",
)

sandbox.delete_saved_snapshot("web-stack")
```

You can also delete snapshots on the [Snapshots](https://boat.dev/dashboard?tab=snapshots) tab of the dashboard.

Deletion and retention responses use `Cache-Control: no-store`.

## What a delete keeps

Sandboxes can share snapshot data. A fork, a resume and a deploy from a saved snapshot read the same data as their source. So a delete erases only the data that nothing else uses. boat keeps:

* The data that a fork of this sandbox still needs.
* Your **saved snapshots** from this sandbox. They exist to outlive it. To remove one, run `boat snapshot rm <name>`.

boat frees the storage when no sandbox and no saved snapshot uses it.

When you remove a saved snapshot, it becomes unavailable at once. boat erases its data **six hours** later at the earliest. Upload links for snapshots stay valid for six hours. This delay stops an upload that already started from making the data again after the delete.

If you enable [zero data retention](https://docs.boat.dev/data-retention/zero-data-retention.md), boat removes your saved snapshots and queues their data for deletion. You cannot save a saved snapshot while ZDR is on.


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