> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Node overview

> What a node is, what the agent does, and what node health means in StackShift.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

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

## Prerequisites

* A connected or planned node

## Workflow

<Steps>
  <Step>
    Treat node health as a scheduling input.
  </Step>

  <Step>
    Treat the agent version as part of the node runtime contract.
  </Step>

  <Step>
    Use maintenance before disruptive node changes.
  </Step>
</Steps>

## 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

<Check>
  You understand how StackShift reasons about node readiness and workload placement.
</Check>

## Related guides

<CardGroup cols={2}>
  <Card title="Install the agent" href="/nodes/install-the-agent">
    Bootstrap a new node and understand what the install command is doing on the target host.
  </Card>

  <Card title="Maintenance mode" href="/nodes/maintenance-mode">
    Use maintenance as a safety control before upgrades or disruptive host changes.
  </Card>

  <Card title="Node health, diagnostics, and deletion" href="/nodes/node-health-diagnostics-and-deletion">
    Read node diagnostics correctly and understand when deletion is safe or blocked.
  </Card>
</CardGroup>