# Windows & macOS Setup Guides

{% hint style="danger" %}
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.
{% endhint %}

{% tabs %}
{% tab title="Windows (WSL2)" %}

#### <mark style="color:$primary;">01 / Prepare Windows (Install WSL2)</mark>

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

```bash
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.

#### <mark style="color:$primary;">02 / Install Geth (Execution Client)</mark>

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

```bash
sudo apt-get update
```

```bash
sudo apt-get install ethereum -y
```

#### <mark style="color:$primary;">03 / Network & Firewall Configuration</mark>

Open the required ports on your Ubuntu firewall:

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

{% hint style="warning" %}
(Hint: You may also need to allow these ports in your Windows Defender Firewall).
{% endhint %}

#### <mark style="color:$primary;">04 / Clone Repository & Initialize Node</mark>

{% hint style="info" %}
🔗 [View ZugChain Validator Suite on GitHub ↗](https://github.com/ZugChainLabs/zugchain-validator-configs)&#x20;
{% endhint %}

Download the ZugChain suite and run the automated installer:

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

```bash
cd zugchain-validator-configs/validator
```

```bash
chmod +x join_network.sh
```

```bash
sudo ./join_network.sh
```

#### <mark style="color:$primary;">05 / Key Generation & Secure Import</mark>

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. <mark style="color:$warning;">Generate Your Keys</mark>

{% hint style="info" %}
🔗 [View ZugChain Official CLI on GitHub ↗](https://github.com/ZugChainLabs/zugchain-deposit-cli)
{% endhint %}

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.

2. <mark style="color:$warning;">Upload Keys to your Server</mark>

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.

{% code title="# Create a folder for your keys" %}

```bash
mkdir -p ~/zug_keys
```

{% endcode %}

{% code title="# Open a text editor (Replace the filename with your actual keystore filename!)" %}

```bash
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.
```

{% endcode %}

{% code title="# Create a text file containing the password you used during generation" %}

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

{% endcode %}

3. <mark style="color:$warning;">Import to the Validator Wallet (CRITICAL)</mark>

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

```bash
/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
```

{% hint style="danger" %}
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:*
{% endhint %}

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

#### <mark style="color:$primary;">06 / Start the Node & Monitor</mark>

*Ignite the background services and check your logs:*

```bash
sudo systemctl start zugchain-validator
```

```bash
sudo apt-get install ccze -y
```

```bash
journalctl -fu zugchain-validator | ccze -A
```

{% endtab %}

{% tab title="macOS" %}

#### <mark style="color:$primary;">01 / Prepare macOS (Create Ubuntu VM)</mark>

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:

{% code title="# Install Homebrew if you don't have it" fullWidth="false" %}

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

{% endcode %}

{% code title="# Install Multipass and launch an Ubuntu VM" fullWidth="false" %}

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

{% endcode %}

{% code title="# Enter the Ubuntu environment" fullWidth="false" %}

```bash
multipass shell zugchain-node
```

{% endcode %}

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

#### <mark style="color:$primary;">02 / Install Geth (Execution Client)</mark>

*Install the execution layer software inside your VM:*

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

```bash
sudo apt-get update
```

```bash
sudo apt-get install ethereum -y
```

#### <mark style="color:$primary;">03 / Network & Firewall Configuration</mark>

*Open the required network ports:*

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

#### <mark style="color:$primary;">04 / Clone Repository & Initialize Node</mark>

{% hint style="info" %}
🔗 [View ZugChain Validator Suite on GitHub ↗](https://github.com/ZugChainLabs/zugchain-validator-configs)
{% endhint %}

*Download the ZugChain suite and run the automated installer:*

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

```bash
cd zugchain-validator-configs/validator
```

```bash
chmod +x join_network.sh
```

```bash
sudo ./join_network.sh
```

#### <mark style="color:$primary;">05 / Key Generation & Secure Import</mark>

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. <mark style="color:$warning;">Generate Your Keys</mark>

{% hint style="info" %}
🔗 [View ZugChain Official CLI on GitHub ↗](https://github.com/ZugChainLabs/zugchain-deposit-cli)
{% endhint %}

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.

2. <mark style="color:$warning;">Upload Keys to your Server</mark>

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.

{% code title="# Create a folder for your keys" %}

```bash
mkdir -p ~/zug_keys
```

{% endcode %}

{% code title="# Open a text editor (Replace the filename with your actual keystore filename!)" %}

```bash
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.
```

{% endcode %}

{% code title="# Create a text file containing the password you used during generation" %}

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

{% endcode %}

3. <mark style="color:$warning;">Import to the Validator Wallet (CRITICAL)</mark>

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

```bash
/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
```

{% hint style="danger" %}
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:*
{% endhint %}

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

#### <mark style="color:$primary;">06 / Start the Node & Monitor</mark>

*Ignite the background services and check your logs:*

```bash
sudo systemctl start zugchain-validator
```

```bash
sudo apt-get install ccze -y
```

```bash
journalctl -fu zugchain-validator | ccze -A
```

{% endtab %}
{% endtabs %}


---

# 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://zugchain.gitbook.io/zugchain/validator-operations/windows-and-macos-setup-guides.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.