Goal
Understand nodes as runtime machines with operational state, not just a list in the UI.Prerequisites
- A connected or planned node
Workflow
What the node page surfaces
- Health, agent version state, and last update timing
- CPU, memory, disk, Docker, and Caddy readiness signals
- Recovery-state details when a tracked node-side workflow is in trouble
Node status states
- pending: registered but not yet confirmed healthy.
- healthy: passing checks and schedulable.
- degraded: reachable but a readiness signal is unhappy — investigate before relying on it.
- maintenance: intentionally held out of scheduling (see maintenance mode).
- offline: no recent heartbeat — the agent is not reporting in.
- failed / deleting: errored or being removed.
Health is a scheduling input
StackShift places workloads on healthy nodes. A node that is offline (stale heartbeat), degraded, or in maintenance is treated differently by placement, so node health is not just a status badge — it directly decides where new workloads can land. Keeping the agent current is part of that contract.Expected result
You understand how StackShift reasons about node readiness and workload placement.
Related guides
Install the agent
Bootstrap a new node and understand what the install command is doing on the target host.
Maintenance mode
Use maintenance as a safety control before upgrades or disruptive host changes.
Node health, diagnostics, and deletion
Read node diagnostics correctly and understand when deletion is safe or blocked.