01 // Overview

This document describes how to prepare for, install, and operate a SHH Ghost Node once public node access is enabled in Phase 2 (Mainnet Beta). Ghost Nodes act as Zero-Knowledge Validators, mixing liquidity and validating proofs without seeing underlying transaction data.

The commands below are designed to be technically realistic and follow common patterns used by production blockchain clients (Docker + systemd). Exact binaries, image names, and endpoint URLs may change and will be announced before Phase 2 launch.

02 // Minimum requirements

Hardware

• CPU: 4 dedicated 64-bit cores (x86_64)
• RAM: 16 GB
• Storage: 200 GB NVMe SSD (or faster)
• Network: 100 Mbps symmetric connection (or better)
• Uptime: 99.5% availability target

Operating system

We recommend a minimal Linux distribution:

• Ubuntu Server 22.04 LTS
• Debian 12
• Or equivalent 64‑bit Linux with systemd

Dependencies

• Docker (24.x or newer) or containerd
• docker compose plugin (or docker-compose)
• OpenSSL for key generation

03 // Installation

When public binaries are released, a one-line installer will be available. Until then, the commands below describe the expected flow.

1. Create a dedicated user

sudo adduser --system --group --home /var/lib/shh shh
sudo mkdir -p /var/lib/shh
sudo chown -R shh:shh /var/lib/shh

2. Install Docker (if not already installed)

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker shh
newgrp docker

3. Fetch the SHH node image (placeholder)

The final image name will be announced. For now, we assume the canonical registry registry.shh.network/shh-node:

docker pull registry.shh.network/shh-node:latest

04 // Configuration

1. Generate node keys

Each Ghost Node needs a long‑lived identity keypair and an operator wallet.

sudo -u shh mkdir -p /var/lib/shh/keys
cd /var/lib/shh/keys

# Node identity key (example using openssl)
openssl genpkey -algorithm ed25519 -out node_identity.key
openssl pkey -in node_identity.key -pubout -out node_identity.pub

Operator wallet creation will depend on the target L1 (e.g., Ethereum). As a placeholder, we assume you will connect an existing wallet via the web dashboard and get an operator token:

# Placeholder: this token will be issued by the SHH web dashboard
echo "SHH_OPERATOR_TOKEN=replace-with-real-token" > /var/lib/shh/operator.env

2. Create a configuration file

sudo -u shh cat > /var/lib/shh/config.toml << 'EOF'
[node]
id_key_path = "/var/lib/shh/keys/node_identity.key"
data_dir    = "/var/lib/shh/data"
network     = "mainnet-beta"   # or "testnet" when available

[p2p]
listen_addr   = "0.0.0.0:31000"
max_peers     = 128

[rpc]
listen_addr   = "127.0.0.1:8547"
metrics_addr  = "127.0.0.1:9101"

[operator]
token_env_var = "SHH_OPERATOR_TOKEN"
rewards_addr  = "REPLACE_WITH_OPERATOR_WALLET"
EOF

05 // Running the node

Option A: Docker Compose (recommended)

Create a small docker-compose.yml in /var/lib/shh:

cd /var/lib/shh
sudo -u shh cat > docker-compose.yml << 'EOF'
services:
  ghost-node:
    image: registry.shh.network/shh-node:latest
    restart: unless-stopped
    user: "1000:1000"          # replace with output of: id -u shh ; id -g shh
    env_file:
      - /var/lib/shh/operator.env
    volumes:
      - /var/lib/shh/config.toml:/app/config.toml:ro
      - /var/lib/shh/data:/app/data
      - /var/lib/shh/keys:/app/keys:ro
    network_mode: "host"
EOF

Then start the service:

cd /var/lib/shh
docker compose up -d

Option B: systemd service (advanced)

You can also manage the node via systemd for better integration with your OS:

sudo tee /etc/systemd/system/shh-node.service > /dev/null << 'EOF'
[Unit]
Description=SHH Ghost Node
After=network-online.target docker.service
Wants=network-online.target

[Service]
User=shh
Group=shh
Restart=always
RestartSec=5
EnvironmentFile=/var/lib/shh/operator.env
ExecStart=/usr/bin/docker run --rm \\
  --name shh-node \\
  --network host \\
  -v /var/lib/shh/config.toml:/app/config.toml:ro \\
  -v /var/lib/shh/data:/app/data \\
  -v /var/lib/shh/keys:/app/keys:ro \\
  registry.shh.network/shh-node:latest

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now shh-node

06 // Monitoring, logs & updates

Logs

If you are running via Docker Compose:

cd /var/lib/shh
docker compose logs -f ghost-node

Via systemd:

sudo journalctl -u shh-node -f

Health & metrics

By default the node exposes:

• http://127.0.0.1:8547/health — basic health probe
• http://127.0.0.1:9101/metrics — Prometheus‑style metrics

Upgrading

To upgrade to the latest image while using Docker Compose:

cd /var/lib/shh
docker compose pull
docker compose up -d