# 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="build-your-node" %}
[build-your-node](https://docs.constellationnetwork.io/run-a-node/validator-node-guides/build-your-node)
{% endcontent-ref %}

{% content-ref url="../legacy/the-nodectl-utility" %}
[the-nodectl-utility](https://docs.constellationnetwork.io/run-a-node/legacy/the-nodectl-utility)
{% 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="../references/ssh-remote-access" %}
[ssh-remote-access](https://docs.constellationnetwork.io/run-a-node/references/ssh-remote-access)
{% 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.