An operation starts fresh compute from an image and runs your command as its primary process. When that process ends, the service stops any remaining subprocesses and finishes the operation.
To reuse changed files, choose to save them before starting the operation. Then use the image UUID returned in its result. Saving an image does not keep the runtime alive.
Lifecycle
For example, one operation can install dependencies and save an image. The next starts from those installed files on fresh compute. A server started during installation must be started again if the next operation needs it.
The primary process determines when finalization begins. Additional subprocesses share its VM, filesystem, resources, and operation lifetime. A subprocess result does not create a separate image.
Operation states
The public operation API exposes these states:
SUCCESS is an operation state. A process can still report a nonzero exit code, signal, or timeout in its result. Check the process result before using its output or saved image.
Separate lifetimes
Client request or wait
A response, disconnect, or client-side limit ends the wait. Query the operation before submitting duplicate work.
SSE subscription
The stream can complete, fail, or disconnect independently of execution. Resume with the last fully processed event ID when supported, then inspect terminal status.
Operation compute
Compute ends when the primary workload finalizes, cancellation completes, or the platform fails the operation. Running processes, memory, and connections end with it.
Stored image
The image remains available until it is removed or reaches the applicable retention boundary. Reuse its immutable UUID only while the image is available.
Do not treat a REST SSE disconnect as cancellation. Resume the stream or query the operation before deciding whether to retry. SDK 0.3.6 follows a different path: when its internal wait exits without observing a terminal state, it attempts to cancel the operation. Handle transport disconnects, SDK wait failures, execution timeouts, and explicit cancellation as separate cases.
Results and recovery
SUCCESS with exit code 0
The command completed successfully. Inspect output and the returned image before continuing.
SUCCESS with a nonzero exit code
The service ran the command, which reported failure. Correct the command or input and start a new operation from a known image.
Process timed_out=true
The guest execution reached its configured limit. Inspect signal, exit state, output, and result-image fields. Do not assume timeout persistence.
CANCELLED
The operation stopped after cancellation. Confirm terminal status and result-image availability before retrying.
FAILED or a client exception
No normal successful operation result is available. Keep the operation ID and redacted error details; inspect status before retrying.
Choose the next image using the result-image rules.
Continue
