跳转到主要内容

​
DevBox Lifecycle v0

​
Scope

Defines the minimum lifecycle model for AIOS DevBox in v0, including desired-state semantics, observed phases, legal transitions, and execution gating rules used by Gateway, Probe, Scheduler, and self-heal flows. This page formalizes the lifecycle baseline derived from Sealos-inspired state handling and the accepted AIOS freeze decisions.

​
Terminology

  • Desired state: control-plane target written by Gateway.
  • Observed phase: execution-side state reported by Probe.
  • Converging transition: a transition that requires orderly cleanup such as channel close, command cancel, and metadata flush.
  • Recovering: explicit intermediate phase for bounded local recovery.

​
Normative Spec

​
State Model

DevBox lifecycle in v0 uses a two-level model:

​
Desired state

  • running
  • paused
  • stopped
  • terminated
shutdown MAY be accepted as an input alias but MUST converge to stopped as the normalized state representation in the v0 documentation baseline.

​
Observed phase

  • pending
  • running
  • pausing
  • paused
  • stopping
  • stopped
  • recovering
  • failed
  • terminated
  • unknown

​
Authority Rules

  • Gateway MUST own desired-state mutation.
  • Probe MUST report observed phase and MUST NOT rewrite desired state.
  • Any execution action MUST hold a valid lease before mutating local runtime state.

​
Transition Rules

  • running -> paused is allowed and MUST converge through pausing -> paused.
  • paused -> running is allowed and MUST converge back through pending or directly to running when immediately ready.
  • running -> stopped is allowed and MUST follow a converging stop path.
  • paused -> stopped is allowed and MUST follow a converging stop path.
  • stopped -> running is allowed and MAY include warm-up through pending.
  • running -> terminated is allowed and MUST follow a converging termination path.
  • paused -> terminated is allowed and MUST follow a converging termination path.
  • stopped -> terminated is allowed as final teardown.
  • terminated -> stopped MUST be rejected.
  • terminated -> running MUST be rejected in v0.
  • failed -> running MAY occur only through an explicit recovery path that succeeds.

​
Converging Transition Actions

For converging lifecycle actions, the control flow MUST follow: observe -> diff -> preflight -> mutate -> health-check -> emit The following actions are mandatory during converging stop/terminate flows:
  • channel close
  • command cancel
  • metadata flush
Snapshot creation MAY be applied according to snapshot policy but is not mandatory for every transition.

​
Execution Gating

New execution work MUST only be admitted when observed phase is compatible with execution. The v0 recommended execution-admit phases are:
  • pending
  • running
  • paused only when the action is explicitly resume-related
The following phases MUST NOT accept new execution work:
  • pausing
  • stopping
  • recovering
  • failed
  • terminated
  • unknown

​
Recovering Phase

  • Any non-terminal state MAY enter recovering for bounded local repair.
  • Exceeding recovery budget MUST escalate and converge to failed or a Gateway-directed action.

​
Examples

​
Transition examples

Current desiredTarget desiredResultNotes
runningpausedallowedpausing -> paused
pausedrunningallowedresume to pending/running
runningstoppedallowedconverging stop path required
stoppedterminatedallowedfinal teardown
terminatedrunningrejectedv0 requires new DevBox

​
Phase derivation example

{
  "desired_state": "running",
  "observed_phase": "recovering",
  "reason": "ssh_remote_attach_failed"
}

​
Error & Recovery

  • Illegal transition requests MUST be rejected and audited.
  • Loss of Probe or critical channel readiness MAY push the runtime into recovering.
  • Recovery beyond budget MUST escalate to Gateway rather than looping indefinitely.

​
Security & Audit

  • Every transition MUST be traceable through correlation and lifecycle events.
  • Desired-state authority remains centralized in Gateway.
  • Lifecycle convergence MUST respect approval, lease, and metadata-only audit boundaries.

​
Status

Current status: draft Source discussions:
  • docs/maintainers/conversation-records/agent-platform/2026-03-23-devbox-lifecycle-transition-matrix-v0-draft.md
  • docs/maintainers/conversation-records/agent-platform/2026-03-23-sealos-devbox-lifecycle-reference.md
  • docs/maintainers/conversation-records/agent-platform/2026-03-24-p1-freeze-result-accepted.md

​
Changelog

  • 2026-03-24: Initial formal lifecycle specification created from frozen discussion baseline.

​
相关页面