> ## 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 named snapshot, and follow the deletion operation until the data is erased.

A delete is permanent. You cannot resume a deleted sandbox.

## 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, restores and forks immediately.
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 issued for it expires. This is at most six hours after the last upload. |
| `kept_for_newer_snapshots` | A newer snapshot that you kept uses this one as its base. Boat erases this data when it erases those snapshots. |
| `waiting_for_restore` | A sandbox still restores from it. |
| `retrying` | A transient fault occurred. Boat retries automatically. |
| `completed` | Boat erased the stored data. |

<Warning>
  You cannot cancel a deletion operation.
</Warning>

## Delete a sandbox

Every sandbox or snapshot delete needs the header `X-Ascii-Confirm-Delete`. Its value must be exactly the target id. The CLI and the dashboard set this header for you.

<CodeGroup>
  ```bash CLI theme={null}
  boat delete bx_f7k2q9hd          # asks first, then follows the operation to completion
  boat delete bx_f7k2q9hd --yes    # no prompt, for scripts
  ```

  ```bash curl theme={null}
  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={null}
  const accepted = await sandbox.deleteSandbox({
    sandboxId: "bx_f7k2q9hd",
    xAsciiConfirmDelete: "bx_f7k2q9hd",
  });
  console.log(accepted.operation.id, accepted.operation.status);
  ```

  ```python Python theme={null}
  accepted = sandbox.delete_sandbox(
      x_ascii_confirm_delete="bx_f7k2q9hd",
      sandbox_id="bx_f7k2q9hd",
  )
  print(accepted.operation.id, accepted.operation.status)
  ```
</CodeGroup>

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

## Poll the operation

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

<CodeGroup>
  ```bash CLI theme={null}
  boat deletion status bdop_0123456789abcdef0123456789abcdef
  ```

  ```bash curl theme={null}
  curl -sS "$BOAT_API_BASE/deletion-operations/$OPERATION_ID" \
    -H "Authorization: Bearer $BOAT_API_KEY"
  ```

  ```ts TypeScript theme={null}
  const current = await sandbox.getDeletionOperation({ operationId: accepted.operation.id });
  console.log(current.operation.status);   // pending | processing | blocked | completed
  ```

  ```python Python theme={null}
  current = sandbox.get_deletion_operation(accepted.operation.id)
  print(current.operation.status)
  ```
</CodeGroup>

`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 ordinary snapshot | The snapshot id |
| `DELETE /sandboxes/{sandboxId}/snapshots` | Every ordinary snapshot of one sandbox. The sandbox stays. | The sandbox id |
| `DELETE /named-snapshots/{name}` | One named snapshot, by name | None |

<CodeGroup>
  ```bash CLI theme={null}
  boat snapshot delete <snapshotId>     # one ordinary filesystem snapshot
  boat snapshot delete --all bx_f7k2q9hd  # every ordinary snapshot of a sandbox
  boat snapshot rm web-stack            # a named snapshot, by name
  ```

  ```bash curl theme={null}
  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/named-snapshots/web-stack" \
    -H "Authorization: Bearer $BOAT_API_KEY"
  ```

  ```ts TypeScript theme={null}
  await sandbox.deleteSnapshot({
    snapshotId: "<snapshotId>",
    xAsciiConfirmDelete: "<snapshotId>",
  });

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

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

  ```python Python theme={null}
  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_named_snapshot("web-stack")
  ```
</CodeGroup>

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

## Shared and named snapshots

* A sandbox delete does not delete a named snapshot that you saved from it.
* A named snapshot is an independent shared artifact.
* A named snapshot can share deduplicated storage with other snapshots.
* Boat removes the stored objects only when no kept artifact uses them.

When you remove a named snapshot, it becomes unavailable immediately. Boat schedules the deletion of its data **six hours** later at the earliest. Snapshot upload URLs stay valid for six hours. This delay stops an upload that already started from creating the data again after the delete.

If you enable [zero data retention](/data-retention/zero-data-retention), Boat removes your named snapshots and queues their data for deletion. You cannot create a named snapshot while ZDR is on.


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