Operation Lifecycle

Every cell lifecycle request creates or reuses an operation. SQLite is the source of truth for operations, events, steps, idempotency keys, and cell state.

state 01Requesteddurably accepted

→

state 02Runningsteps + events

→

terminalSucceededfinal result

Failure pathrunning work or interrupted requests terminate as failed

Records

• operations stores the high-level operation state and target id.
• operation_events stores append-only state and domain events such as operation.running, cell.ready, and operation.succeeded.
• operation_steps stores explicit step records such as persist-cell, create-machine, start-machine, stop-machine, and destroy-machine.
• idempotency_keys scopes request replay by operation kind and key.

Idempotency

Idempotency is per endpoint kind. Repeating CreateCell with the same key returns the original create operation. Reusing the same key for StartCell and StopCell produces independent operations because they are different operation kinds.

Startup Reconciliation

When celld starts, it loads persisted non-destroyed cells and asks the selected backend to reconcile desired state with host reality:

• ready cells become ready machines;
• running cells become running machines;
• stopped cells become stopped machines;
• destroyed cells are not restored into the backend.

The fake backend rebuilds in-memory machines. The container backend rehydrates live Docker-backed machines and workspace paths. The Firecracker backend compares runtime descriptors with live processes, TAP devices, and vsock sockets, then cleans orphans and marks missing expected runtimes failed.

Operations left in requested or running are conservatively marked failed and receive a startup-reconciliation failed step. DevCell records the interruption rather than silently replaying privileged work.