Delete a sandbox or snapshot

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

How a delete works

You send a delete request.
Boat returns 202 Accepted with an operation.
The sandbox or snapshot disappears from lists, restores and forks immediately.
Boat erases the stored data in the background, when nothing reads it any more.
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.

You cannot cancel a deletion operation.

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.

boat delete bx_f7k2q9hd          # asks first, then follows the operation to completion
boat delete bx_f7k2q9hd --yes    # no prompt, for scripts

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

const accepted = await sandbox.deleteSandbox({
  sandboxId: "bx_f7k2q9hd",
  xAsciiConfirmDelete: "bx_f7k2q9hd",
});
console.log(accepted.operation.id, accepted.operation.status);

accepted = sandbox.delete_sandbox(
    x_ascii_confirm_delete="bx_f7k2q9hd",
    sandbox_id="bx_f7k2q9hd",
)
print(accepted.operation.id, accepted.operation.status)

In the dashboard, open 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.

boat deletion status bdop_0123456789abcdef0123456789abcdef

curl -sS "$BOAT_API_BASE/deletion-operations/$OPERATION_ID" \
  -H "Authorization: Bearer $BOAT_API_KEY"

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

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

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

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"

await sandbox.deleteSnapshot({
  snapshotId: "<snapshotId>",
  xAsciiConfirmDelete: "<snapshotId>",
});

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

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

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")

You can also delete snapshots on the 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, Boat removes your named snapshots and queues their data for deletion. You cannot create a named snapshot while ZDR is on.

​How a delete works

​Delete a sandbox

​Poll the operation

​Delete one snapshot

​Shared and named snapshots

How a delete works

Delete a sandbox

Poll the operation

Delete one snapshot

Shared and named snapshots