> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Execution lifecycle

> Understand operations, processes, client waits, event streams, and saved images.

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

```mermaid theme={null}
flowchart TB
  A[Input image] --> B[Choose save or discard]
  B --> C
  subgraph runtime[Temporary compute]
    C[Primary process runs]
    C --> D[Primary process ends]
    D --> E[Stop children<br/>and finalize]
  end
  E --> F[Output and result]
  F --> G{Saved image?}
  G -->|Yes| H[Reuse its UUID]
  G -->|No| I[No saved state]
```

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:

| State | Meaning for a caller |
| - | - |
| `PENDING` | The operation is waiting to be assigned. |
| `ASSIGNED` | Resources have been assigned; execution may be starting. |
| `EXECUTING` | The operation is running. Wait for an application readiness signal before starting a subprocess that depends on the primary workload. |
| `SUCCESS` | The service completed the operation. Inspect the process exit code, signal, timeout flag, output, and result image separately. |
| `FAILED` | The service could not complete the operation. Use the operation error and ID for diagnosis. |
| `CANCELLED` | Cancellation reached a terminal operation state. Inspect the response before assuming a result image exists. |

<Note>
  `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.
</Note>

## 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](/sandboxes/concepts/images-checkpoints-and-branches#interpret-the-result-image).

## Continue

* [Images, checkpoints, and branches](/sandboxes/concepts/images-checkpoints-and-branches)
* [Sessions and execution modes](/sandboxes/concepts/sessions-and-execution-modes)
* [Run commands and handle results](/sandboxes/guides/run-commands-and-results)
* [Stream output and events](/sandboxes/guides/stream-output-and-events)
* [Run subprocesses and send input](/sandboxes/guides/run-subprocesses-and-send-input)
* [Operation status reference](/api-reference/sandboxes/operations/get-an-operation-status)