Running a Node

This guide walks you through setting up and running a NONOS node from start to finish.

Prerequisites

Before you begin, ensure you have:

A server meeting hardware requirements
NOX tokens for staking (minimum 1,000 NOX)
An Ethereum wallet with your NOX tokens
Basic command-line familiarity

Installation

Option 1: Quick Install (Recommended)

# Download and install
curl -sSL https://get.nonos.systems | sh

# Verify installation
nonos --version

Option 2: Build from Source

# Clone repository
git clone https://github.com/NON-OS/nonos-ecosystem
cd nonos-ecosystem

# Build release binary
cargo build --release --bin nonos

# Install to PATH
sudo cp target/release/nonos /usr/local/bin/

Option 3: Docker

# Pull official image
docker pull nonos/daemon:latest

# Run container
docker run -d \
  --name nonos-node \
  -p 9000:9000 \
  -p 8420:8420 \
  -v ~/.nonos:/root/.nonos \
  -e NONOS_WALLET_KEY="your-private-key" \
  nonos/daemon:latest

Initial Configuration

Step 1: Initialize Node

nonos init --reward-address 0xYourEthereumAddress

This creates:

~/.nonos/config.toml - Configuration file
~/.nonos/identity - Node identity keypair
~/.nonos/data/ - Storage directory

Step 2: Configure Settings

Edit ~/.nonos/config.toml:

[node]
# Human-readable name for your node
name = "my-nonos-node"

# Data storage location
data_dir = "/home/user/.nonos/data"

# P2P listen address
listen_addr = "/ip4/0.0.0.0/tcp/9000"

[api]
# Local API binding
bind_address = "127.0.0.1"
port = 8420

# Enable Prometheus metrics export
prometheus = true

[network]
# Bootstrap nodes (defaults are included)
bootstrap_nodes = [
    "/dns4/bootstrap1.nonos.systems/tcp/9000/p2p/12D3KooW...",
    "/dns4/bootstrap2.nonos.systems/tcp/9000/p2p/12D3KooW..."
]

# Maximum peer connections
max_peers = 50

[staking]
# Ethereum RPC endpoint
rpc_url = "https://ethereum-rpc.publicnode.com"

# Or use your own node
# rpc_url = "http://localhost:8545"

[rewards]
# Address to receive rewards
reward_address = "0xYourEthereumAddress"

# Enable auto-claim (optional)
auto_claim = false
auto_claim_threshold = 100  # NOX

[services]
# Enable all privacy services
health_beacon = true
quality_oracle = true
cache = true
cache_size_mb = 256

Step 3: Set Environment Variables

# Required for staking operations
export NONOS_WALLET_KEY="your-ethereum-private-key"

# Optional: Custom data directory
export NONOS_DATA_DIR="/path/to/data"

# Optional: Custom API port
export NONOS_API_PORT=8420

# Optional: Log level
export NONOS_LOG_LEVEL=info  # trace, debug, info, warn, error

Security Note: Never commit your private key to version control or share it.

Staking

Check Your Balance

nonos stake status

Output:

Stake Status
══════════════════════════════════════════════════════
Address:   0xYourAddress...
Staked:    0 NOX
Tier:      None
Available: 15,000 NOX
══════════════════════════════════════════════════════

Deposit Stake

# Stake 10,000 NOX
nonos stake deposit 10000

Output:

Staking 10,000 NOX...
Step 1/2: Approving tokens...
  Tx: 0xabc123...
Step 2/2: Depositing stake...
  Tx: 0xdef456...
[+] Successfully staked 10,000 NOX!

Select Tier

# View available tiers
nonos stake tiers

# Select a tier
nonos stake tier silver

Starting the Node

Foreground Mode (Development)

nonos run

Output:

    ███╗   ██╗ ██████╗ ███╗   ██╗ ██████╗ ███████╗
    ████╗  ██║██╔═══██╗████╗  ██║██╔═══██╗██╔════╝
    ██╔██╗ ██║██║   ██║██╔██╗ ██║██║   ██║███████╗
    ██║╚██╗██║██║   ██║██║╚██╗██║██║   ██║╚════██║
    ██║ ╚████║╚██████╔╝██║ ╚████║╚██████╔╝███████║
    ╚═╝  ╚═══╝ ╚═════╝ ╚═╝  ╚═══╝ ╚═════╝ ╚══════╝

        Decentralized Node Daemon - v1.0.0

╔══════════════════════════════════════════════════════════════╗
║  NONOS Daemon is now running!                                ║
╠══════════════════════════════════════════════════════════════╣
║  Node ID: 0x7a3b9c4d...                                      ║
║  API: http://127.0.0.1:8420                                  ║
╠══════════════════════════════════════════════════════════════╣
║  Services Active:                                            ║
║    [+] ZK Identity Engine                                    ║
║    [+] Cache Mixer (Poseidon Merkle)                         ║
║    [+] Tracking Blocker                                      ║
║    [+] Stealth Scanner                                       ║
║    [+] P2P Network (libp2p)                                  ║
╠══════════════════════════════════════════════════════════════╣
║  Run 'nonos dash' in another terminal for TUI dashboard      ║
║  Press Ctrl+C to stop                                        ║
╚══════════════════════════════════════════════════════════════╝

Background Mode

Using systemd (Linux)

Generate service file:

nonos systemd --output-dir /etc/systemd/system --user nonos

This creates /etc/systemd/system/nonos.service:

[Unit]
Description=NONOS Daemon
After=network-online.target
Wants=network-online.target

[Service]
Type=notify
User=nonos
Group=nonos
ExecStart=/usr/local/bin/nonos run --systemd
Restart=on-failure
RestartSec=10

Environment="NONOS_WALLET_KEY=your-key"
Environment="NONOS_DATA_DIR=/var/lib/nonos"

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/nonos

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable nonos
sudo systemctl start nonos

# Check status
sudo systemctl status nonos

# View logs
sudo journalctl -u nonos -f

Using launchd (macOS)

Create ~/Library/LaunchAgents/systems.nonos.daemon.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>systems.nonos.daemon</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/nonos</string>
        <string>run</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
        <key>NONOS_WALLET_KEY</key>
        <string>your-key</string>
    </dict>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/usr/local/var/log/nonos.log</string>
    <key>StandardErrorPath</key>
    <string>/usr/local/var/log/nonos.error.log</string>
</dict>
</plist>

Load and start:

launchctl load ~/Library/LaunchAgents/systems.nonos.daemon.plist

Monitoring

Terminal Dashboard

nonos dash

Features:

Real-time metrics visualization
Peer connection status
Reward tracking
Quality score display

API Endpoints

# Node status
curl http://localhost:8420/api/status

# Detailed metrics
curl http://localhost:8420/api/metrics

# Privacy stats
curl http://localhost:8420/api/privacy/stats

# Health check
curl http://localhost:8420/api/health

Prometheus Metrics

Available at http://localhost:8420/api/metrics/prometheus:

# HELP nonos_requests_total Total requests handled
# TYPE nonos_requests_total counter
nonos_requests_total 12345

# HELP nonos_uptime_seconds Node uptime
# TYPE nonos_uptime_seconds gauge
nonos_uptime_seconds 86400

# HELP nonos_quality_score Current quality score
# TYPE nonos_quality_score gauge
nonos_quality_score 0.95

Claiming Rewards

Check Pending Rewards

nonos rewards status

Manual Claim

nonos rewards claim

Enable Auto-Claim

# Claim automatically when pending rewards reach 100 NOX
nonos rewards auto --threshold 100

Maintenance

Updating

# Stop node
nonos stop

# Update binary
curl -sSL https://get.nonos.systems | sh

# Restart
nonos run

Backup

Important files to backup:

# Node identity (critical!)
~/.nonos/identity

# Configuration
~/.nonos/config.toml

# ZK identities
~/.nonos/identities/

Log Rotation

# Configure logrotate
sudo cat > /etc/logrotate.d/nonos << EOF
/var/log/nonos/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0640 nonos nonos
}
EOF

Common Commands

# Node operations
nonos run                    # Start node
nonos stop                   # Stop node
nonos status                 # Check if running
nonos info                   # Show node info

# Staking
nonos stake status           # Show stake info
nonos stake deposit <amount> # Stake tokens
nonos stake withdraw <amount># Unstake tokens
nonos stake tiers            # Show tier info

# Rewards
nonos rewards status         # Show pending
nonos rewards claim          # Claim rewards
nonos rewards history        # View history

# Diagnostics
nonos check                  # Run diagnostics
nonos peers list             # Show connected peers
nonos stats                  # Network statistics

# Identity management
nonos identity generate      # New ZK identity
nonos identity list          # List identities
nonos identity prove <id>    # Generate proof

Next Steps

Configuration Guide - Advanced configuration options
Monitoring & Dashboard - Detailed monitoring setup
Troubleshooting - Common issues and solutions

Need help? Check the FAQ or join our community Discord.

PreviousNode Architecture NextHardware Requirements

Last updated 1 month ago

Was this helpful?

hashtagPrerequisites

hashtagInstallation

hashtagOption 1: Quick Install (Recommended)

hashtagOption 2: Build from Source

hashtagOption 3: Docker

hashtagInitial Configuration

hashtagStep 1: Initialize Node

hashtagStep 2: Configure Settings

hashtagStep 3: Set Environment Variables

hashtagStaking

hashtagCheck Your Balance

hashtagDeposit Stake

hashtagSelect Tier

hashtagStarting the Node

hashtagForeground Mode (Development)

hashtagBackground Mode

hashtagMonitoring

hashtagTerminal Dashboard

hashtagAPI Endpoints

hashtagPrometheus Metrics

hashtagClaiming Rewards

hashtagCheck Pending Rewards

hashtagManual Claim

hashtagEnable Auto-Claim

hashtagMaintenance

hashtagUpdating

hashtagBackup

hashtagLog Rotation

hashtagCommon Commands

hashtagNext Steps

Prerequisites

Installation

Option 1: Quick Install (Recommended)

Option 2: Build from Source

Option 3: Docker

Initial Configuration

Step 1: Initialize Node

Step 2: Configure Settings

Step 3: Set Environment Variables

Staking

Check Your Balance

Deposit Stake

Select Tier

Starting the Node

Foreground Mode (Development)

Background Mode

Monitoring

Terminal Dashboard

API Endpoints

Prometheus Metrics

Claiming Rewards

Check Pending Rewards

Manual Claim

Enable Auto-Claim

Maintenance

Updating

Backup

Log Rotation

Common Commands

Next Steps