Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Understand nodes as runtime machines with operational state, not just a list in the UI.

​
Prerequisites

  • A connected or planned node

​
Workflow

1
Treat node health as a scheduling input.
2
Treat the agent version as part of the node runtime contract.
3
Use maintenance before disruptive node changes.

​
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.

Install the agent

Enroll a qualified Linux host with a ten-minute single-use ticket, signed bootstrap artifacts, WireGuard, and a rotating mTLS node identity.

Maintenance mode

Use maintenance as a safety control before upgrades or disruptive host changes.

Node health, diagnostics, and deletion

Interpret overlay, mTLS, heartbeat, runtime, operation, inventory, and explicit deletion-blocker state before taking action.