# Workspace snapshots

Point-in-time workspace checkpoints — SAND-WP-0007.

## Overview

Snapshots capture the remote workspace state of a **ready** sandbox without
destroying it. Restore provisions a **new** sandbox from the checkpoint.

| Operation | CLI | HTTP |
|-----------|-----|------|
| Create checkpoint | `sandboxer snapshot <sandbox_id>` | `POST /v1/sandboxes/{id}/snapshot` |
| Restore | `sandboxer restore <snapshot_id>` | `POST /v1/snapshots/{id}/restore` |
| List | `sandboxer snapshots list` | `GET /v1/snapshots` |
| Get | `sandboxer snapshots get <id>` | `GET /v1/snapshots/{id}` |

Snapshot metadata is stored at `~/.local/share/sandboxer/snapshots.json`.
Extension artifacts (e.g. tarballs) live on the placement host.

## Profile

`profile.compose-checkpoint` binds `ext.compose-ssh` for checkpoint-enabled
compose sandboxes. Use the same `inputs.repo` convention as `profile.compose-e2e`.

## ext.compose-ssh behavior

1. **Snapshot** — `tar czf` of `remote_dir` to `{base_dir}/snapshots/{id}.tar.gz`
2. **Restore** — new `sandbox_id`, extract tarball, `compose up -d`

Cross-host restore is not supported in v0 (artifact must be on the target host).

## ext.saas-stub

Metadata-only checkpoints for routing and payments tests. Restore reprovisions
a fresh stub endpoint.

## Extension contract

Optional hooks on `SandboxExtension`:

```python
def supports_snapshots(self) -> bool: ...
def snapshot(self, handle) -> dict[str, str]: ...
def restore_from_snapshot(self, profile, snapshot_meta, inputs, host) -> dict[str, str]: ...
```

See `docs/extension-sdk.md`.