Add scheduled instance snapshots with retention cleanup

[sjmiller609]

Summary

• add per-instance snapshot schedule configuration (get/set/delete)
• add background scheduler that runs due schedules and creates snapshots automatically
• add retention cleanup for scheduled snapshots (max_count / max_age)
• update snapshot/instance README docs for scheduled snapshot behavior
• extend OpenAPI and regenerate SDK/server bindings

API

• GET /instances/{id}/snapshot-schedule
• PUT /instances/{id}/snapshot-schedule
• DELETE /instances/{id}/snapshot-schedule

Notes

• schedule configs are stored centrally under the data dir (not in guest snapshot payloads), so schedule state is not forked/restored with VM payload snapshots.

Testing

• go test ./lib/instances -run SnapshotSchedule -count=1
• go test ./cmd/api/api -run Snapshot -count=1
• go test ./cmd/api -run TestOapiRuntimeBindStyledParameter_URLDecoding -count=1

---

Note

Medium Risk
Adds new background scheduling/cleanup logic that creates and deletes snapshots automatically, which could impact data retention and storage if scheduling/retention rules behave unexpectedly.

Overview
Adds per-instance scheduled snapshots via new GET/PUT/DELETE /instances/{id}/snapshot-schedule endpoints, including request validation (duration parsing, required retention) and a new SnapshotSchedule API model.

Implements schedule persistence under a new snapshot-schedules/ data directory and a background scheduler in cmd/api/main.go that polls every minute to run due schedules, auto-select snapshot kind based on instance state, record run status (next_run_at, last_* fields), and apply retention cleanup (max_count/max_age) only to scheduled snapshots.

Introduces a small lib/scheduledsnapshots package for schedule validation/naming/storage helpers, adds ErrSnapshotScheduleNotFound, updates docs, and regenerates OpenAPI server/client bindings; includes unit tests covering schedule lifecycle, retention, deleted-instance behavior, and zero-value retention serialization/mapping.

^{Written by Cursor Bugbot for commit 1104580. 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: Add scheduled instance snapshots with retention cleanup

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ hypeman-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

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

New diagnostics (3 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /instances/{id}/snapshot-schedule`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `put /instances/{id}/snapshot-schedule`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `delete /instances/{id}/snapshot-schedule`

✅ hypeman-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅

New diagnostics (3 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /instances/{id}/snapshot-schedule`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `put /instances/{id}/snapshot-schedule`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `delete /instances/{id}/snapshot-schedule`

✅ hypeman-go studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

go get github.com/stainless-sdks/hypeman-go@48499eca9f51d8343660506b2e6bab77af8f997f

New diagnostics (3 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /instances/{id}/snapshot-schedule`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `put /instances/{id}/snapshot-schedule`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `delete /instances/{id}/snapshot-schedule`

---

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-10 20:59:19 UTC

[cursor]

Stale comment

Automated Risk Assessment

Medium-High risk. Review is required, so this PR is not approved by automation.

Evidence from the diff:

• Adds a new background scheduler loop in cmd/api/main.go that periodically executes snapshot schedule runs.
• Introduces substantial new scheduling and retention logic in lib/instances/snapshot_schedule.go, including automatic snapshot deletion paths.
• Expands public API surface with new snapshot-schedule endpoints in cmd/api/api/snapshots.go and openapi.yaml (plus regenerated bindings in lib/oapi/oapi.go).
• Changes are cross-cutting across API, runtime behavior, persistence, and cleanup semantics, increasing regression and operational blast radius.

Validation notes:

• Attempted targeted tests, but they could not run in this environment due missing embedded binary assets under lib/vmm, lib/system, and lib/ingress.

Action taken:

• Requested reviewers: rgarcia, hiroTamada.

---

  

[cursor]

Automated Risk Assessment

Medium-High risk. Review is required, so this PR is not approved by automation.

Assessment based on the code diff:

• Adds a new minute-polling background scheduler in cmd/api/main.go that executes asynchronous snapshot work continuously.
• Introduces substantial new scheduling/retention execution logic in lib/instances/snapshot_schedule.go, including automatic snapshot deletion paths.
• Expands production API surface via new schedule endpoints in cmd/api/api/snapshots.go and schema/binding changes in openapi.yaml and lib/oapi/oapi.go.
• Persists and loads schedule state on disk (lib/scheduledsnapshots/storage.go, lib/paths/paths.go), increasing operational/state-management complexity.

Reviewer handling:

• Code review is required for this risk level.
• No additional reviewer requests were made because 2 reviewers are already assigned (hiroTamada, rgarcia).

---

  

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

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

[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.}

[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.}