The Container Lifecycle

In one sentence: A container is a state machine — created, running, paused, exited, dead — and every CLI command is just a request for one specific transition.

States are promises

Each state is a promise about what exists. Created: filesystem mounted, config written, network allocated — but no process; you can inspect it, copy files in, but it consumes no CPU. Running: the process lives. Paused: the process exists but its cgroup is frozen — mid-instruction, consuming memory but zero CPU. Exited: the process is gone but the writable layer and logs remain — debuggable, restartable. Dead: removal failed partway; a tombstone. Removal is only legal from a stopped state — run is not a state but a composite: create + start.

stateDiagram-v2
  [*] --> Created: create (fs + config ready, no process)
  Created --> Running: start
  Running --> Paused: pause (cgroup freeze)
  Paused --> Running: unpause
  Running --> Exited: process exits or stop/kill
  Exited --> Running: restart
  Created --> [*]: rm
  Exited --> [*]: rm
  Running --> [*]: rm -f (force)
  Exited --> Dead: rm failed midway
  Dead --> [*]: rm (retry cleanup)
    

Who moves the needle

Transitions have two sources: user commands (start, pause, stop) and reality — the process can exit on its own at any moment, and the state machine must follow the world, not fight it:

sequenceDiagram
  participant U as User
  participant E as Engine
  participant CS as Container store
  participant S as Shim
  U->>E: start c-42
  E->>CS: state: Created → Running
  note over S: hours later, the app segfaults
  S->>E: exit event (code 139)
  E->>CS: state: Running → Exited (139)
  U->>E: pause c-42
  E-->>U: error: container not running