Fork VM

[sjmiller609]

• add fork support for stopped/standby instances, including metadata cloning, snapshot rewrites, and network identity handling
• introduce forkvm utilities for copying guest directories and rewriting cloud-hypervisor snapshot configs with tests and README
• expand restore flow to allocate fresh network identities when forking standby instances

Summary

• implement instance.ForkInstance with validation, locking, hypervisor restrictions, and metadata duplication
• add forkvm package (copy + snapshot helpers) with unit tests and README documentation
• ensure standby restores detect forked snapshots and reallocate network identities before launching

Testing

• Added integration test

---

Note

High Risk
High risk because it introduces a new instance lifecycle operation that manipulates VM disk/snapshot state and network identity across multiple hypervisors, and it changes the standby restore networking flow (including in-guest reconfiguration).

Overview
Adds a new POST /instances/{id}/fork API and OpenAPI client/server bindings, allowing creation of a new instance cloned from a source in Stopped/Standby (and Running when from_running=true), with request validation and conflict/state error mapping.

Implements instances.Manager.ForkInstance with directory cloning, metadata deep-copying, optional post-fork state transitions, safety checks (e.g., writable volumes rejected), and hypervisor-specific fork preparation via a new hypervisor.VMStarter.PrepareFork hook (implemented for Cloud Hypervisor, QEMU, and Firecracker; explicitly unsupported for VZ).

Updates standby RestoreInstance to support forked snapshots by allocating a fresh network identity when needed, rewriting snapshot network config before restore, and reconfiguring guest networking after resume; Firecracker restore also adds a temporary source->target data-dir alias mechanism for snapshot path compatibility. CI test timeout is increased to 20m and new unit/integration tests + fork documentation are added.

^{Written by Cursor Bugbot for commit 9f362af. 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 cloud hypervisor VM forking helpers

✅ hypeman-openapi studio · code

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

⚠️ 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/2bdda88d46adce289f72f5f18eb5f1329651cd33/dist.tar.gz

⏳ hypeman-go studio · code

generate ✅ → build ⏳ → lint ✅ → test ✅

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

⏳ These are partial results; builds are still running.

---

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-02 21:28:06 UTC

[hiroTamada]

Solid implementation of VM forking. Good separation of concerns between filesystem copy (forkvm), hypervisor-specific snapshot rewrites (CH/QEMU), and orchestration logic. Network identity handling for forked standby instances is well thought out - fresh allocation + guest reconfiguration addresses the IP conflict issue properly.

Test coverage is comprehensive, including integration tests for the full running→fork→both-running flow.

LGTM.

[sjmiller609]

pulling in support for firecracker and vz if I can

[sjmiller609]

Submitting pending review so I can reply directly on the thread.

[cursor]

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

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

[rgarcia]

looks great! have you tested with kernel-images image? i'm fine leaving vz as a separate PR

[sjmiller609]

have you tested with kernel-images image?

I haven't checked that yet. Will follow up if there are issues, I expect to use this feature as part of cpu based pooling