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

# Upgrade the agent

> Use the maintenance-first path to move an existing node to a newer agent version.

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

## Goal

Update the node agent without leaving it in a confused scheduling state.

## Prerequisites

* A connected node
* Maintenance access

## Workflow

<Steps>
  <Step>
    Put the node into maintenance.
  </Step>

  <Step>
    Apply the upgrade command or reinstall flow.
  </Step>

  <Step>
    Verify heartbeat freshness and version state before returning the node to service.
  </Step>
</Steps>

## How the upgrade path is framed

* StackShift exposes copyable upgrade commands from the node page.
* Maintenance mode is the expected safety gate before upgrading.
* The UI distinguishes “upgrade available” from a real failed upgrade operation.

## Why maintenance first

Upgrading restarts the agent, which briefly disrupts heartbeats and the node-side workflows it runs. Draining the node into maintenance first keeps the scheduler from placing new work mid-upgrade, so the restart does not collide with a fresh deployment.

## After the upgrade

* Confirm a fresh heartbeat and the expected agent version on the node page.
* An "upgrade available" badge is informational — it is not the same as a failed upgrade operation.
* Return the node to service (activate) only once it reports healthy.

## Expected result

<Check>
  The node reports the expected agent version and can safely leave maintenance.
</Check>

## Related guides

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

  <Card title="Node overview" href="/nodes/node-overview">
    What a node is, what the agent does, and what node health means in StackShift.
  </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>