# First Time Cluster Connection

## :warning: Guide Usage

This guide assumes that you have properly created and connected to your VPS successfully and installed the nodectl utility.

{% content-ref url="/pages/g2sw1EO34xv3WRmGYo1S" %}
[Build Your Node](/run-a-node/validator-node-guides/build-your-node.md)
{% endcontent-ref %}

{% content-ref url="/pages/iyN9F9FN3uZzDTmrPWgs" %}
[The nodectl utility](/run-a-node/legacy/the-nodectl-utility.md)
{% endcontent-ref %}

## 🧰 Prerequisites

Before beginning, ensure you’ve reviewed the full checklist and profile documentation.

* This guide uses `dag-l0` as the profile name.
* Replace `dag-l0` with your node’s actual profile name if it differs.
  * For example `dor-dl1` for Dor data layer1 validator nodes.

***

## 🔐 SSH Into Your VPS

Use the following command to connect to your VPS via SSH:

```bash
ssh -i /path/to/ssh/private/key root@<vps_ip_address>
```

{% content-ref url="/pages/SZ8YBbmpjJILqGWxrmx5" %}
[SSH Remote Access](/run-a-node/references/ssh-remote-access.md)
{% endcontent-ref %}

***

## 📄 Verify Your Node Is on the Seed List

To confirm that your node is recognized by the network, run:

```bash
sudo nodectl check_seedlist -p dag-l0
```

Expected Output:

```
NODE ID FOUND ON SEED LIST
True
```

> 🛑 If you are **not** on the seed list, stop here and contact a **Discord Administrator Team Lead** via the Constellation Network Official Discord.\
> You must wait for the next cluster restart that includes a seed list update before continuing.

***

#### ⬆️ Perform a Node Upgrade

Use the upgrade command to prepare your node for the cluster connection:

```bash
sudo nodectl upgrade -ni
```

> The `-ni` flag enables **non-interactive mode**, accepting default values automatically.

***

#### ⚙️ For Single Layer1 Nodes

If you're operating a Layer1-only Metagraph Validator, you may skip directly to the **Join Layer1** step at the bottom of this guide.

***

#### 🧬 For Hybrid Nodes

Hybrid nodes must reach a **Ready** state on Layer0 before joining Layer1.

**⚠️ Expected Behavior:**

After your node completes Layer0 connection steps, it will attempt to join the Layer1 profile and **fail**. This is **expected** and not a concern at this stage.

> This happens because Layer1 participation is blocked until your node fully syncs the Layer0 snapshot chain.

During this period, your node will transition through the following statuses:

* `SessionStarted`
* `DownloadInProgress`

***

#### 📥 Monitor for DownloadInProgress State

After upgrading, verify your node has reached the correct syncing phase:

```bash
sudo nodectl status -p dag-l0
```

Expected Output:

```
JOIN STATE
DownloadInProgress
```

If you see `SessionStarted`, continue running the command periodically until it transitions to `DownloadInProgress`.

***

#### ⏳ Wait for Ready State

Your node will now download the entire snapshot chain from the Layer0 cluster. This process may take **several days**.

You have two options:

* **Wait** for your node to reach the `Ready` state.
* **Proceed to the optional next step** to speed up the snapshot process using the Starchiver utility.

***

#### 🚀 Optional: Execute Starchiver to Speed Up Sync

To accelerate snapshot syncing:

```bash
sudo nodectl execute_starchiver -p dag-l0 --restart
```

> 👀 Monitor your node closely to ensure the process completes without error.

> 🚧 **Caution:**\
> `Starchiver` is a community-supported tool and **not officially supported** by Constellation Network. Use at your own risk.\
> For issues, contact the tool's maintainer via GitHub or seek help on the Constellation Discord.

***

#### 📊 Verify Node Status

Once your node has completed downloading the snapshot chain, it will enter the `Ready` state and begin participating in consensus.

To verify:

```bash
sudo nodectl status -p dag-l0
```

Look for the following:

```
Layer0
JOIN STATE       Ready
IN CONSENSUS     True
```

For Layer1:

```
Layer1
JOIN STATE       ReadyToJoin
```

> 🔄 To monitor the transition in real time:

```bash
sudo nodectl status -p dag-l0 -w 120
```

Use the `q` key to exit the watch command gracefully.

***

#### 🔗 Join Layer1 (For Hybrid Nodes Only)

If Layer1 displays `ReadyToJoin`, you may initiate the join process:

```bash
sudo nodectl join -p dag-l1
```

If your node is in **any other state**, restart the profile before retrying:

```bash
sudo nodectl restart -p dag-l1
```

***

Once the above steps are complete and your node is fully synced and participating in consensus, your first-time connection process is complete.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.constellationnetwork.io/run-a-node/validator-node-guides/first-time-cluster-connection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.