---
id: SAND-WP-0007
type: workplan
title: "Snapshot restore and checkpoint profiles"
domain: infotech
repo: sand-boxer
status: finished
owner: codex
topic_slug: custodian
created: "2026-06-24"
updated: "2026-06-24"
state_hub_workstream_id: "bb4e0e63-6323-49c1-be4a-cc7691494d24"
---

# Snapshot restore and checkpoint profiles

Workspace checkpoint API for self-hosted compose sandboxes and SaaS stub.

**Predecessor:** SAND-WP-0006 (SaaS extensions — finished)  
**Follow-on:** SAND-WP-0009 (TTL), cross-host snapshot transfer, E2B/Modal persistence

## Snapshot store and models

```task
id: SAND-WP-0007-T01
status: done
priority: high
state_hub_task_id: "aff7daf8-8fc2-40ae-bb4b-4549afd1659e"
```

`SnapshotRecord`, `SnapshotStore` at `~/.local/share/sandboxer/snapshots.json`.

## Extension hooks

```task
id: SAND-WP-0007-T02
status: done
priority: high
state_hub_task_id: "3e0570a3-09d7-43ca-8df7-ec2c9b51f3be"
```

Optional `supports_snapshots`, `snapshot`, `restore_from_snapshot` on
`SandboxExtension`. Reference: `ext.compose-ssh` (remote tar), `ext.saas-stub`
(metadata stub).

## Manager orchestration

```task
id: SAND-WP-0007-T03
status: done
priority: high
state_hub_task_id: "9b63f7db-d1bf-4b86-8046-6f8f2d8d78ed"
```

`SandboxManager.snapshot`, `restore`, `list_snapshots`, `get_snapshot`. Restore
provisions a new sandbox; source sandbox stays ready.

## CLI and HTTP API

```task
id: SAND-WP-0007-T04
status: done
priority: high
state_hub_task_id: "c4e7ae42-5c15-470a-9ef0-56596f82d1a0"
```

CLI: `snapshot`, `restore`, `snapshots list|get`. HTTP:
`POST /v1/sandboxes/{id}/snapshot`, `POST /v1/snapshots/{id}/restore`,
`GET /v1/snapshots`.

## Profile and docs

```task
id: SAND-WP-0007-T05
status: done
priority: medium
state_hub_task_id: "5512f009-b888-437f-8e29-0f6975e8f024"
```

`profile.compose-checkpoint`, `docs/snapshots.md`, updates to `extension-sdk.md`,
`meta-framework.md`, `SCOPE.md`.

## Tests

```task
id: SAND-WP-0007-T06
status: done
priority: high
state_hub_task_id: "d805e110-7fe6-4dfb-bf8c-d0ee0ad78456"
```

`tests/test_snapshots.py`, compose-ssh snapshot tests, API stubs, manager flow.