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

# Upgrade an executor

> Request an upgrade from the UI; the executor self-applies and reports the new version

Upgrading an executor moves it to a newer Novacula release — a new binary for an Agent, a new container image for an Operator. You start the upgrade from the UI, and the executor applies it on its own. You don't run anything by hand on the host or cluster.

Upgrading also unlocks newer support: once an executor is on a newer release, any chains, clients, or versions it now declares become available in the deploy wizard.

## Prerequisites

* A role that can manage executors: **owner** or **admin**.
* An upgrade target offered for your executor (see [How upgrades are offered](#how-upgrades-are-offered)).

The executor does **not** have to be online to receive an upgrade. If it's offline, Novacula queues the upgrade and the executor applies it on its next check-in after it reconnects.

## How upgrades are offered

In the sidebar, open **Executors**, pick your row, and find the **Version & Updates** panel. It shows the current version and any available upgrades and downgrades.

Only releases **one major version away** can be applied directly. If you're more than one major behind, the upgrade happens in two hops: upgrade to the next reachable major first, then to your target. Releases that are too far ahead still appear in the picker, but they're disabled and labelled `requires upgrade to N.x first`.

## Upgrade from the UI

<Steps>
  <Step title="Open the executor">
    In the sidebar, open **Executors** and pick your row. The **Version & Updates** panel lists the current version and what you can move to.
  </Step>

  <Step title="Choose a release">
    Click **Update to** the latest version for a one-click jump, or **Upgrade…** to pick a specific release. Each candidate shows its version; a target that's too far ahead is disabled and labelled `requires upgrade to N.x first`.
  </Step>

  <Step title="Confirm">
    Novacula queues the upgrade on the executor. The panel shows a pending banner with the target version while the job is in flight.
  </Step>

  <Step title="Wait for the executor to apply">
    On its next check-in the executor downloads and applies the new version, then reports back; the row shows the new version. If the new version fails to start, the executor rolls back automatically to the version it was running.

    If the executor never picks the job up, the pending banner times out and offers **Retry**. You can also **Cancel** a pending upgrade at any time.
  </Step>
</Steps>

## Downgrades and rollback

To move back to an earlier release — for example while you investigate a regression — use **Downgrade…** in the same **Version & Updates** panel and pick an older version. The same one-major-version reachability applies.

<Note>
  Older executors don't know about clients or versions introduced later. Before downgrading, confirm your nodes' chains and client versions are still supported by the target release.
</Note>

You rarely need to roll back by hand: a release that fails to start is reverted automatically. A downgrade is for stepping back to a version that runs fine but that you no longer want.

## Staying current

An executor that falls behind keeps working — your nodes and data stay reachable regardless of how old it is. Nothing is blocked when a release ages out; keeping the executor current just unlocks newer chains, clients, and versions in the deploy wizard.