Repository navigation
Add force option to instance stop - #573
Conversation
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 35b0667. Configure here.
| guest state will be discarded, for example before restoring a snapshot. | ||
| A forced stop of a macOS guest is never graceful, so it cannot be used | ||
| for a stopped snapshot or fork until the guest is booted and stopped | ||
| gracefully again. |
There was a problem hiding this comment.
Stop request model missing SDK mapping
Medium Severity
StopInstanceRequest is added as a named OpenAPI schema and as the /instances/{id}/stop request body, but stainless.yaml is not updated with a corresponding model mapping. The stop method is already listed, yet the new request schema is not, so Stainless SDK previews can omit the force field and leave SDK clients unable to request a forced stop.
Reviewed by Cursor Bugbot for commit 35b0667. Configure here.
-->
✱ stlc build✅ go code · compare
✅ python code · compare
✅ typescript code · compare
Diagnostics: ❗ 0 new / 1 total error, 💡 0 new / 5 total note
Build metadata
This comment is auto-generated by stlc and is kept up to date as you push. |


Summary
POST /instances/{id}/stoponly does a graceful stop: it asks the guest to shut down, waits up to the grace period, and falls back to a hypervisor shutdown. That wait is wasted when the guest state is about to be thrown away, for example right before restoring a memory snapshot to reset a VM. On a macOS guest the graceful stop takes about 7s.This adds an optional body to stop,
{"force": true}, which skips the guest shutdown and goes straight to the existing hypervisor shutdown path. With no body or{"force": false}, stop behaves as before. The naming follows other platforms' hard-stop options (AWSStopInstances --force, Hyper-VStop-VM -TurnOff).Existing and new flows
Everything after that (network release, socket cleanup, snapshot dir removal, metadata) is unchanged.
Behavior
stop_gracefulstays false), so a stopped snapshot or fork from that stop returns 409 until the guest is booted and stopped gracefully again. On VZ the hypervisor shutdown is the shim'svmm.shutdown(VZVirtualMachine.stop(), then a clean shim exit), so the vmnet network is released. It does not SIGKILL the shim unless the shim fails to exit.{}now covers/stopas well. It is renamedNormalizeOptionalStandbyBody->NormalizeOptionalBody. Existing callers that POST stop with no body keep working.StopInstanceRequest{}and keep the graceful behavior.instances.stopspan and the "stopping instance" log carryforce.Change size
~1,210 lines changed; roughly 70 LOC of meaningful implementation (approximate, excluding generated code, tests, docs and the call-site signature updates):
lib/instances/stop.gocmd/api/api/optional_body.go/standbyand/stopopenapi.yaml+ handler +StopInstanceRequestlib/oapi/oapi.gomake oapi-generateStopInstancesignature update, new tests, macOS doc noteTesting
go test ./lib/instances -run TestForceStopSkipsGuestShutdown— passes; fails withForce: false, confirming it detects the guest shutdown RPC.go test ./cmd/api/api -run TestNormalizeOptionalBody— passes, including the new empty/stopbody case.go test ./lib/instanceson a Linux VM without KVM ormkfs.erofs: 24 failures, the same set as onmainin that environment.Manual, on an Apple silicon Mac (macOS 27, macOS 27.0.1 guest, 4 vCPU / 8 GiB):
Stopped, no shim process left,stop_gracefulfalsemacOS fork requires a gracefully stopped source)stop_gracefultrueManual, Linux smoke test on a KVM dev host (throwaway test, not committed): nginx guest with networking, cycle forced stop -> start -> graceful stop -> start -> forced stop. Each stop checked
Stopped, the hypervisor PID gone and the TAP device removed; each start checked the exec agent answers and the guest has an IP.Not run: QEMU, and CI.
Not included
timeout_seconds). The stored per-instanceStopTimeoutis still not exposed in the API.