Windows & macOS Setup Guides

Linux Exclusivity Notice: The native ZugChain validator suite is designed exclusively for Linux environments. However, you can perfectly run the network on Windows or macOS by using local Ubuntu virtualization. Follow your operating system's complete A-to-Z guide below.

Windows (WSL2)

01 / Prepare Windows (Install WSL2)

To run the node, we first need to activate Windows' built-in Linux subsystem. Open PowerShell as Administrator and run:

wsl --install

After installation, restart your PC. Open the new "Ubuntu" application from your Windows Start Menu. You will do all following steps inside this Ubuntu terminal.

02 / Install Geth (Execution Client)

sudo add-apt-repository -y ppa:ethereum/ethereum

sudo apt-get update

sudo apt-get install ethereum -y

03 / Network & Firewall Configuration

Open the required ports on your Ubuntu firewall:

sudo ufw allow 30303
sudo ufw allow 13000/tcp
sudo ufw allow 12000/udp
sudo ufw allow 3500/tcp
sudo ufw enable

(Hint: You may also need to allow these ports in your Windows Defender Firewall).

04 / Clone Repository & Initialize Node

🔗 View ZugChain Validator Suite on GitHub ↗

Download the ZugChain suite and run the automated installer:

git clone https://github.com/ZugChainLabs/zugchain-validator-configs.git

cd zugchain-validator-configs/validator

chmod +x join_network.sh

sudo ./join_network.sh

05 / Key Generation & Secure Import

To participate in consensus and earn rewards, the blockchain needs to recognize you via cryptographic keys. You must generate these keys offline, deposit exactly 32,000 ZUG using them, and then import them into your server safely.

1. Generate Your Keys

🔗 View ZugChain Official CLI on GitHub ↗

Go to the official CLI tool linked above. Follow the instructions to generate a new mnemonic (passphrase) and your validator keys. It will produce a JSON file named something like keystore-m_12381_3600_0_0_0-123456.json. You must remember the password you used to encrypt it.

1. Upload Keys to your Server

You need to transfer the generated JSON file over to your Linux/Ubuntu environment. The easiest way for beginners is to copy the text inside the file and paste it into a new file on your server.

# Create a folder for your keys

mkdir -p ~/zug_keys

# Open a text editor (Replace the filename with your actual keystore filename!)

nano ~/zug_keys/keystore-m_12381_3600_0_0_0-123456.json

# PASTE THE CONTENTS OF YOUR FILE HERE.
# Press Ctrl+O, then Enter to save. Press Ctrl+X to exit.

# Create a text file containing the password you used during generation

echo "YOUR_KEYSTORE_PASSWORD" > ~/zug_keys/password.txt

1. Import to the Validator Wallet (CRITICAL)

Now, securely import your key into the Validator Client's local database:

/usr/local/bin/validator accounts import \
    --keys-dir=$HOME/zug_keys \
    --wallet-dir=/opt/zugchain/data/validators \
    --account-password-file=$HOME/zug_keys/password.txt

CRITICAL - Auto-Restart Requirement: During the import step above, the terminal will ask you to create a NEW Wallet Password. You MUST immediately save this password into a specific file using the command below, or your validator will fail to restart:

echo "YOUR_NEW_WALLET_PASSWORD" > /opt/zugchain/data/validators/wallet-password.txt

06 / Start the Node & Monitor

Ignite the background services and check your logs:

sudo systemctl start zugchain-validator

sudo apt-get install ccze -y

journalctl -fu zugchain-validator | ccze -A

macOS

01 / Prepare macOS (Create Ubuntu VM)

Because ZugChain uses native Linux tools, we will create an isolated Ubuntu environment right on your Mac using Multipass (works perfectly on Apple Silicon M1/M2/M3 and Intel). Open your Mac Terminal and run:

# Install Homebrew if you don't have it

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Multipass and launch an Ubuntu VM

brew install multipass
multipass launch ubuntu --name zugchain-node --memory 8G --disk 500G --cpus 4

# Enter the Ubuntu environment

multipass shell zugchain-node

You are now inside Ubuntu! Run all following steps in this terminal.

02 / Install Geth (Execution Client)

Install the execution layer software inside your VM:

sudo add-apt-repository -y ppa:ethereum/ethereum

sudo apt-get update

sudo apt-get install ethereum -y

03 / Network & Firewall Configuration

Open the required network ports:

sudo ufw allow 30303
sudo ufw allow 13000/tcp
sudo ufw allow 12000/udp
sudo ufw allow 3500/tcp
sudo ufw enable

04 / Clone Repository & Initialize Node

🔗 View ZugChain Validator Suite on GitHub ↗

Download the ZugChain suite and run the automated installer:

git clone https://github.com/ZugChainLabs/zugchain-validator-configs.git

cd zugchain-validator-configs/validator

chmod +x join_network.sh

sudo ./join_network.sh

05 / Key Generation & Secure Import

To participate in consensus and earn rewards, the blockchain needs to recognize you via cryptographic keys. You must generate these keys offline, deposit exactly 32,000 ZUG using them, and then import them into your server safely.

1. Generate Your Keys

🔗 View ZugChain Official CLI on GitHub ↗

Go to the official CLI tool linked above. Follow the instructions to generate a new mnemonic (passphrase) and your validator keys. It will produce a JSON file named something like keystore-m_12381_3600_0_0_0-123456.json. You must remember the password you used to encrypt it.

1. Upload Keys to your Server

You need to transfer the generated JSON file over to your Linux/Ubuntu environment. The easiest way for beginners is to copy the text inside the file and paste it into a new file on your server.

# Create a folder for your keys

mkdir -p ~/zug_keys

# Open a text editor (Replace the filename with your actual keystore filename!)

nano ~/zug_keys/keystore-m_12381_3600_0_0_0-123456.json
# PASTE THE CONTENTS OF YOUR FILE HERE.
# Press Ctrl+O, then Enter to save. Press Ctrl+X to exit.

# Create a text file containing the password you used during generation

echo "YOUR_KEYSTORE_PASSWORD" > ~/zug_keys/password.txt

1. Import to the Validator Wallet (CRITICAL)

Now, securely import your key into the Validator Client's local database:

/usr/local/bin/validator accounts import \
    --keys-dir=$HOME/zug_keys \
    --wallet-dir=/opt/zugchain/data/validators \
    --account-password-file=$HOME/zug_keys/password.txt

CRITICAL - Auto-Restart Requirement: During the import step above, the terminal will ask you to create a NEW Wallet Password. You MUST immediately save this password into a specific file using the command below, or your validator will fail to restart:

echo "YOUR_NEW_WALLET_PASSWORD" > /opt/zugchain/data/validators/wallet-password.txt

06 / Start the Node & Monitor

Ignite the background services and check your logs:

sudo systemctl start zugchain-validator

sudo apt-get install ccze -y

journalctl -fu zugchain-validator | ccze -A