Skip to main content

Linux Host-Native Installation

This guide covers installing and running monod natively on a Linux host using systemd for process management. This is the recommended approach for production validators.

Recommended Tool

For a streamlined setup experience, use Monarch CLI which handles installation, configuration, and process management automatically.

Prerequisites​

Before installing Monolythium, ensure your system meets these requirements:

System Requirements​

  • OS: Ubuntu 24.04 LTS or later (other distributions supported)
  • Architecture: x86_64 (amd64) or ARM64
  • CPU: 4+ cores recommended for validators
  • RAM: 16GB+ recommended
  • Storage: 500GB+ SSD (NVMe recommended for validators)

Software Prerequisites​

If downloading pre-built binaries:

  • No additional dependencies required

If building from source:

  • Go 1.25.7+ (required for building monod)
  • make and gcc (build tools)

Install Go:

# Download Go (check go.dev/dl/ for latest)
wget https://go.dev/dl/go1.25.7.linux-amd64.tar.gz

# Remove old Go installation (if exists)
sudo rm -rf /usr/local/go

# Extract new Go
sudo tar -C /usr/local -xzf go1.25.7.linux-amd64.tar.gz

# Add to PATH
echo 'export PATH=$PATH:/usr/local/go/bin:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc

# Verify installation
go version
# Expected: go version go1.25.7 linux/amd64

Network Requirements​

Ensure the following ports are open:

PortProtocolPurpose
26656TCPP2P (LythiumBFT)
26657TCPRPC (LythiumBFT)
1317TCPREST API (Cosmos SDK)
9090TCPgRPC
8545TCPEVM JSON-RPC
8546TCPEVM WebSocket

For production deployments, run monod as a dedicated non-root user:

# Create monod user with a real shell (needed for interactive commands)
sudo useradd -m -s /bin/bash monod

# Create data directory
sudo mkdir -p /home/monod/.mono
sudo chown -R monod:monod /home/monod/.mono

This isolates the node process and improves security.

File Permissions

If using a dedicated user, run monod commands as that user:

# For single commands
sudo -u monod monod <command>

# For interactive sessions
sudo su - monod

Monarch CLI is the recommended tool for node operators. It replaces the deprecated Mono Commander and provides a complete node management experience with built-in process management via OxidePM.

Install Monarch​

curl -fsSL https://raw.githubusercontent.com/monolythium/monarch-cli/prod/scripts/install.sh | bash

Monarch handles:

  • Joining networks with automatic genesis verification
  • Process management via OxidePM (replaces manual systemd management)
  • Node health monitoring with monarch doctor
  • Validator operations (register, edit, unjail)
  • Key management (account + validator keys)
  • Metrics collection and time-series monitoring
  • Log viewing and rotation

See the Monarch CLI documentation for complete usage.

monod Binary​

Build from Source​

Go Already Installed?

If you installed Go in the Software Prerequisites section above, skip the Go installation below.

# Install build tools
sudo apt-get update && sudo apt-get install -y make gcc

# Install Go (skip if already installed)
wget https://go.dev/dl/go1.25.7.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.7.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin:$(go env GOPATH)/bin

# Clone and build
git clone https://github.com/monolythium/mono-chain.git
cd mono-chain
git checkout v0.1.0
make install

# Move binary to system path
sudo mv $(go env GOPATH)/bin/monod /usr/local/bin/

# Verify
monod version
# Expected: 0.1.0

Find release tags at github.com/monolythium/mono-chain/releases. The current version is v0.1.0.

Verify Installation​

# Check version
monod version

# Check available commands
monod --help

systemd Service Configuration​

systemd manages the monod process, ensuring it starts on boot and restarts on failure.

For standard deployments:

sudo tee /etc/systemd/system/monod.service > /dev/null <<EOF
[Unit]
Description=Monolythium Node
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=monod
Group=monod
WorkingDirectory=/home/monod
ExecStart=/usr/local/bin/monod start --home /home/monod/.mono

# Restart configuration
Restart=on-failure
RestartSec=3
StartLimitInterval=0

# Resource limits
LimitNOFILE=65535
LimitNPROC=4096

# Environment
Environment="HOME=/home/monod"

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/home/monod/.mono

[Install]
WantedBy=multi-user.target
EOF

Enable and Start Service​

# Reload systemd to pick up new unit file
sudo systemctl daemon-reload

# Enable service to start on boot
sudo systemctl enable monod

# Start service now
sudo systemctl start monod

# Check status
sudo systemctl status monod

# View logs
sudo journalctl -u monod -f

systemd Unit File Explained​

DirectivePurpose
User=monodRun as dedicated user (not root)
WorkingDirectory=/home/monodSet process working directory
ExecStart=...Command to start the node
Restart=on-failureAuto-restart on crashes
LimitNOFILE=65535Increase file descriptor limit
ProtectSystem=strictRead-only system directories
ReadWritePaths=/home/monod/.monoAllow writes only to data directory
Using Your User Account

If not using a dedicated monod user, replace:

  • User=monod with User=$USER
  • Group=monod with Group=$USER
  • /home/monod with $HOME

Service Management Commands​

# Start node
sudo systemctl start monod

# Stop node
sudo systemctl stop monod

# Restart node
sudo systemctl restart monod

# Check status
sudo systemctl status monod

# Enable auto-start on boot
sudo systemctl enable monod

# Disable auto-start
sudo systemctl disable monod

# View logs (last 100 lines)
sudo journalctl -u monod -n 100

# Follow logs in real-time
sudo journalctl -u monod -f

# View logs since last boot
sudo journalctl -u monod -b

Verify Checksums​

Always verify binary checksums:

# Download checksum file
curl -LO https://github.com/monolythium/mono-chain/releases/download/${LATEST}/checksums.txt

# Verify
sha256sum -c checksums.txt --ignore-missing

Updating​

Manual Update​

# Stop service
sudo systemctl stop monod

# Download new binary
# ... (same as initial download)

# Start service
sudo systemctl start monod

Troubleshooting​

Permission Denied​

Symptom: bash: /usr/local/bin/monod: Permission denied

Solution:

# Make binary executable
chmod +x /usr/local/bin/monod

# Verify permissions
ls -l /usr/local/bin/monod
# Should show: -rwxr-xr-x

Command Not Found​

Symptom: monod: command not found

Solution:

# Check if binary exists
ls -l /usr/local/bin/monod

# Check PATH
echo $PATH

# Find monod
which monod

# If not in PATH, add to ~/.bashrc
echo 'export PATH=$PATH:/usr/local/bin' >> ~/.bashrc
source ~/.bashrc

Wrong Architecture​

Symptom: cannot execute binary file: Exec format error

Solution:

# Check your architecture
uname -m
# x86_64 = amd64
# aarch64 = arm64

# Verify binary architecture
file /usr/local/bin/monod
# Expected: ELF 64-bit LSB executable, x86-64

# Download correct binary for your architecture

systemd Service Fails to Start​

Symptom: systemctl status monod shows "failed" or "inactive (dead)"

Solution:

# Check detailed status
sudo systemctl status monod

# View recent logs
sudo journalctl -u monod -n 50 --no-pager

# Common issues:
# 1. Wrong user - verify User= matches existing user
# 2. Wrong home directory - verify paths exist
# 3. Binary not found - verify ExecStart= path is correct

# Test command manually
sudo -u monod /usr/local/bin/monod start --home /home/monod/.mono

Permission Issues with Data Directory​

Symptom: permission denied errors in logs when accessing ~/.mono/

Solution:

# Fix ownership (if using dedicated user)
sudo chown -R monod:monod /home/monod/.mono

# Fix permissions
sudo chmod 700 /home/monod/.mono
sudo chmod 600 /home/monod/.mono/config/priv_validator_key.json
sudo chmod 600 /home/monod/.mono/config/node_key.json

# Verify
sudo -u monod ls -la /home/monod/.mono/config/

Port Already in Use​

Symptom: bind: address already in use

Solution:

# Find process using port 26656 (or other ports)
sudo lsof -i :26656

# Kill conflicting process (if safe)
sudo kill <PID>

# Or change port in config.toml
vim ~/.mono/config/config.toml
# Find: laddr = "tcp://0.0.0.0:26656"
# Change to: laddr = "tcp://0.0.0.0:26666"

Out of Disk Space​

Symptom: no space left on device

Solution:

# Check disk usage
df -h

# Check monod directory size
du -sh ~/.mono/data

# Prune old data (if running archive node)
# WARNING: This removes historical state
monod prune --home ~/.mono

# Or increase disk size (recommended)

Sync Stuck or Very Slow​

Symptom: Node syncing slowly or stuck at specific height

Solution:

# Check peer count
curl localhost:26657/net_info | jq '.result.n_peers'
# Should be > 5 for good sync performance

# Update peers
monarch peers update --network Testnet

# Restart to pick up new peers
sudo systemctl restart monod

# Consider using state-sync instead
# See: https://docs.monolythium.com/operators/state-sync

SELinux Blocking Access (RHEL/CentOS)​

Symptom: Permission errors despite correct ownership/permissions

Solution:

# Check SELinux status
getenforce

# Temporarily set to permissive (for testing)
sudo setenforce 0

# Permanently disable (if needed)
sudo vim /etc/selinux/config
# Set: SELINUX=permissive

# Or configure proper SELinux policies (recommended)

Next Steps​

After successful installation: