Snapshot

[sjmiller609]

Note

High Risk
Adds new snapshot lifecycle operations that copy/replace VM guest directories and interact with hypervisor standby/restore flows, so bugs could lead to data loss or broken instance state transitions. Also expands the public API surface and manager interface, requiring careful validation across hypervisors.

Overview
Adds a centrally managed snapshot feature for instances, including storage under data/snapshots/ with metadata + guest payload, and new manager methods (CreateSnapshot, RestoreSnapshot, ForkSnapshot, List/Get/DeleteSnapshot) plus ErrSnapshotNotFound.

Exposes snapshots via new HTTP endpoints (POST /instances/{id}/snapshots, POST /instances/{id}/snapshots/{snapshotId}/restore, GET/DELETE /snapshots, GET /snapshots/{snapshotId}, POST /snapshots/{snapshotId}/fork) with updated generated oapi client/server types and response parsing.

Implements snapshot semantics for Standby vs Stopped kinds (including target-state defaults, hypervisor override only for stopped snapshots, sparse-copy enforcement, name uniqueness, and read-only volume safety), updates fork target-state transitions to re-check guest-agent readiness for running returns, and adds integration/unit coverage across Firecracker/QEMU/Cloud Hypervisor/VZ.

^{Written by Cursor Bugbot for commit 34aa764. This will update automatically on new commits. Configure here.}

[github-actions]

✱ Stainless preview builds

This PR will update the hypeman SDKs with the following commit message.

feat: Snapshot

✅ hypeman-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

✅ hypeman-go studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ⏭️ → lint ✅ → test ✅

go get github.com/stainless-sdks/hypeman-go@c4a0fbb34ee2b325229f6a02ae9cc3c57346788d

⚠️ hypeman-typescript studio · code

Your SDK build had at least one "error" diagnostic.
generate ❗ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/hypeman-typescript/ecb2c7652e4180b6bbb87c2f564ba7759c1c792b/dist.tar.gz

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-03-07 03:28:41 UTC

[sjmiller609]

depends on #123

[cursor]

Stale comment

Automated risk assessment for this PR:

• Risk level: Medium-High
• Code review required: Yes
• Approval status from automation: Not approved

Evidence from diff (code-based only):

• Introduces a new snapshot lifecycle in core runtime paths (lib/instances/snapshot.go, lib/instances/manager.go, lib/instances/types.go) including create/list/get/delete/restore/fork behavior.
• Changes fork/copy semantics to sparse extent copying with platform-specific behavior (lib/forkvm/copy.go, lib/forkvm/copy_sparse_unix.go, lib/forkvm/copy_sparse_unsupported.go), which affects VM data cloning and restore paths.
• Expands external API surface with multiple new snapshot endpoints and schema updates (openapi.yaml, regenerated lib/oapi/oapi.go).

Given the blast radius across instance state transitions, disk snapshot handling, and API contracts, this should be reviewed by domain maintainers before merge.

Requested reviewers: @rgarcia, @hiroTamada.

---

  

[cursor]

Automated risk assessment for this PR:

• Risk level: High
• Code review required: Yes
• Approval status from automation: Not approved

Evidence from the actual diff:

• Adds a new snapshot lifecycle in core instance-management codepaths, including create/list/get/delete/restore/fork flows with state-transition logic and filesystem replacement/copy operations (lib/instances/snapshot.go, lib/instances/manager.go, lib/instances/types.go, lib/instances/errors.go).
• Modifies fork behavior in lifecycle transitions by introducing additional guest-agent readiness gates when returning running instances (lib/instances/fork.go).
• Introduces new API handlers and OpenAPI surface for snapshot management and snapshot-based restore/fork operations (cmd/api/api/snapshots.go, openapi.yaml, regenerated lib/oapi/oapi.go).
• Adds a new snapshot persistence subsystem and storage layout (lib/snapshot/store.go, lib/snapshot/types.go, lib/snapshot/record.go, lib/paths/paths.go).

This is a large cross-cutting behavioral change (24 files, ~4.5k insertions) across VM lifecycle, storage semantics, and external API contracts, with high regression and operational risk.

Reviewer assignment:

• Review is required.
• Two reviewers are already assigned (@rgarcia, @hiroTamada), so no additional reviewer requests were made.

---

  

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}