generated from coulomb/repo-seed
tegwick
952cebf2e9
Add workspace checkpoint API with SnapshotStore, extension hooks on compose-ssh and saas-stub, manager orchestration, CLI/HTTP surface, profile.compose-checkpoint, and docs/tests.
47 lines
1.6 KiB
Markdown
47 lines
1.6 KiB
Markdown
# 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`. |