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

# Node lifecycle

> Start, stop, restart, and delete a node — what each action does and what it means for your data

A node moves through a small set of states, and you drive it with four actions: **Start**, **Stop**, **Restart**, and **Delete**. These change whether the node is running — not how it's configured. To change configuration, see [Edit configuration](/docs/nodes/edit-configuration).

## Take an action

Open a node's detail page (**Nodes** → pick a node) and use the action buttons in the header. The same actions are available from each row in the **Nodes** list. Only the actions that make sense for the node's current state are shown — you can't Stop a node that's already stopped, for example.

| Action      | What it does                                                                                        |
| ----------- | --------------------------------------------------------------------------------------------------- |
| **Start**   | Brings a stopped node back up. It resumes from where it left off — no resync from genesis.          |
| **Stop**    | Halts the node's processes but keeps its data. Use it to pause a node without losing sync progress. |
| **Restart** | Cleanly stops and restarts the node without changing anything. Use it to recover a stuck process.   |
| **Delete**  | Permanently removes the node. This cannot be undone — see the warning below.                        |

Editing a node's configuration restarts it automatically when needed, so you rarely need **Restart** by hand.

Actions take effect on the next reconcile cycle (typically within a few seconds), not instantly. The status badge updates as the executor reports progress.

## Node states

Every node shows a colored status badge. The label tells you exactly where the node is:

| State                    | What it means for you                                                                                                                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Provisioning**         | The node has been created and is being set up. The executor is installing and preparing it; it hasn't reported back yet.                                                                                                                    |
| **Downloading snapshot** | The node is bootstrapping from a snapshot before first start — downloading or extracting it. The node page shows download progress, bytes, speed, attempts, resumes, and any failure detail. See [Snapshot bootstrap](#snapshot-bootstrap). |
| **Starting**             | The processes are launching but aren't healthy yet.                                                                                                                                                                                         |
| **Running**              | Up and healthy. Ready to serve RPC and peer with the network.                                                                                                                                                                               |
| **Syncing**              | Up and healthy, importing blocks to catch up to the chain tip.                                                                                                                                                                              |
| **Stopping**             | A stop is in progress.                                                                                                                                                                                                                      |
| **Stopped**              | Halted on purpose. Data is intact; **Start** resumes it.                                                                                                                                                                                    |
| **Error**                | A process crashed or failed its health checks. The detail page shows an error summary.                                                                                                                                                      |
| **Deleting**             | A delete is in progress; teardown isn't finished yet.                                                                                                                                                                                       |

## Snapshot bootstrap

Chains that seed from a snapshot surface the bootstrap as its own **Downloading snapshot** state on first deploy, instead of sitting in an opaque **Starting** state during a long download. While it runs, the node page shows download progress: downloaded bytes, speed, attempts, resumes, and any failure detail the executor reports.

Bootstrap is recoverable. The snapshot is extracted into a staging directory and promoted into the data directory only once complete, so a failed or interrupted bootstrap never leaves a partial tree behind. Agent-side downloads also resume from where they left off when the remote server supports HTTP range requests. If a snapshot bootstrap fails, the failure is surfaced clearly on the node — even when the node then falls back to syncing from genesis — so you can see what happened rather than guessing. Snapshot download progress also appears as a chart on the [Monitoring](/docs/nodes/monitoring) tab.

If the data directory already holds a synced database, the snapshot step is skipped. See each chain's page for whether and how it bootstraps from a snapshot.

## Stopping vs. deleting

These look similar but are very different for your data.

**Stop** is reversible. It halts the node's processes and leaves everything else in place — the data directory and on-disk chain state are untouched. Starting the node again picks up where it left off, so you don't resync from scratch.

**Delete** is permanent and **destroys the node's data on both backends** — the on-chain state is gone and a same-name re-deploy resyncs from scratch:

* **On bare-metal**, deleting removes the node **and its data directory**. See the [bare-metal recipe](/recipes/provision-on-bare-metal) for details.
* **On Kubernetes**, deleting removes the node **and its storage** — the StatefulSet's persistent volume claims are deleted (and a persistent volume left behind by a `Retain` reclaim policy is cleaned up too), along with the node's config and any RPC ingress/certificates. See the [Kubernetes recipe](/recipes/provision-on-kubernetes).

If a delete lands while a snapshot is still downloading, the in-flight download is aborted and its temporary files are removed too, so nothing is left occupying disk or bandwidth.

<Warning>
  Delete destroys the node's data on **both** bare-metal and Kubernetes — its on-chain state is gone for good and a same-name re-deploy resyncs from scratch. If you might need that data, copy it off before deleting.
</Warning>

## Recovering from an error

When a node is in the **Error** state, the detail page shows what went wrong. From here the available action is **Start**, which relaunches the node's processes — the right move once you've addressed a transient cause (a flaky start, a one-off crash). If the node comes back healthy, it leaves the Error state on its own.

If the error keeps coming back, check the node's [logs](/docs/nodes/logs) for the underlying cause before starting it again.

## Permissions

Start, Stop, Restart, and Delete all require the **Owner** or **Admin** role. Members have read-only access and can view a node's state but not change it. See [Roles and permissions](/docs/platform/roles-and-permissions).