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.

Deployment Mode

This guide covers host-native deployment. For Docker-based deployment, see Docker Node Deployment. Not sure which to choose? See Deployment Modes.

Prerequisites

Before installing Monolythium, ensure your system meets these requirements:

System Requirements

OS: Ubuntu 22.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.24.2+ (required for building monod and Cosmovisor)

Go Version

Use Go 1.24.2 or later. Go 1.24.0 has compatibility issues with some dependencies.

Install Go:

# Download Go 1.24.2 (or latest 1.24.x from https://go.dev/dl/)
wget https://go.dev/dl/go1.24.2.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.24.2.linux-amd64.tar.gz

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

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

Network Requirements

Ensure the following ports are open:

Port	Protocol	Purpose
26656	TCP	P2P (CometBFT)
26657	TCP	RPC (CometBFT)
1317	TCP	REST API (Cosmos SDK)
9090	TCP	gRPC
8545	TCP	EVM JSON-RPC
8546	TCP	EVM WebSocket

Create Dedicated User (Recommended)

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

# Create monod user with no login shell
sudo useradd -r -s /bin/false monod

# Create home directory
sudo mkdir -p /home/monod
sudo chown monod:monod /home/monod

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

This isolates the node process and improves security.

File Permissions

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

sudo -u monod monod <command>

Alternatively, set up sudo access or use su - monod for interactive sessions.

Mono Commander (Recommended)

Mono Commander is the recommended tool for node operators. It simplifies node setup, network joining, and daily operations.

Install Commander

# Download binary
curl -LO https://github.com/monolythium/mono-commander/releases/latest/download/monoctl-linux-amd64
chmod +x monoctl-linux-amd64
sudo mv monoctl-linux-amd64 /usr/local/bin/monoctl

# Verify installation
monoctl --help

Or build from source:

git clone https://github.com/monolythium/mono-commander.git
cd mono-commander
go build -o monoctl ./cmd/monoctl
sudo mv monoctl /usr/local/bin/

Commander handles:

Downloading and verifying official genesis files
Configuring DNS-based seed nodes
Generating systemd service files
Node health monitoring and RPC checks

See the Mono Commander documentation for complete usage.

monod Binary

Download Binary

Download the official pre-built binary:

# Check latest release
LATEST=$(curl -s https://api.github.com/repos/monolythium/mono-core/releases/latest | jq -r '.tag_name')

# Download for Linux amd64
curl -LO https://github.com/monolythium/mono-core/releases/download/${LATEST}/monod-linux-amd64

# Make executable
chmod +x monod-linux-amd64

# Move to path
sudo mv monod-linux-amd64 /usr/local/bin/monod

# Verify
monod version

Build from Source

Prerequisites

# Install Go 1.24+
wget https://go.dev/dl/go1.24.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.0.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

# Verify
go version

Build

# Clone repository
git clone https://github.com/monolythium/mono-core.git
cd mono-core

# Checkout release
git checkout <release-tag>

# Build
make build

# Install
sudo mv build/monod /usr/local/bin/

# Verify
monod version

Verify Installation

# Check version
monod version

# Check available commands
monod --help

Cosmovisor (Recommended)

Cosmovisor manages binary upgrades automatically:

Install Cosmovisor

go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest

Setup Directory Structure

mkdir -p ~/.monod/cosmovisor/genesis/bin
mkdir -p ~/.monod/cosmovisor/upgrades

# Copy current binary
cp /usr/local/bin/monod ~/.monod/cosmovisor/genesis/bin/

Environment Variables

export DAEMON_NAME=monod
export DAEMON_HOME=$HOME/.monod
export DAEMON_ALLOW_DOWNLOAD_BINARIES=false
export DAEMON_RESTART_AFTER_UPGRADE=true

Add to ~/.bashrc or ~/.profile for persistence.

systemd Service Configuration

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

Without Cosmovisor

For standard deployments without automatic upgrades:

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/.monod

# 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/.monod

[Install]
WantedBy=multi-user.target
EOF

With Cosmovisor (Recommended for Production)

For automatic upgrade handling:

Cosmovisor Path

If using a dedicated monod user, you must install Cosmovisor as that user or copy it to a system-wide location. The path below assumes Cosmovisor is installed at /usr/local/bin/cosmovisor.

First, install Cosmovisor to a system-wide location:

# Install cosmovisor (as your regular user with Go)
go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest

# Copy to system-wide location
sudo cp $(go env GOPATH)/bin/cosmovisor /usr/local/bin/

# Verify
/usr/local/bin/cosmovisor version

Then create the systemd service:

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

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

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

# Resource limits
LimitNOFILE=65535
LimitNPROC=4096

# Cosmovisor environment
Environment="DAEMON_NAME=monod"
Environment="DAEMON_HOME=/home/monod/.monod"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_DATA_BACKUP_DIR=/home/monod/.monod/backups"
Environment="HOME=/home/monod"

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

[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

Directive	Purpose
`User=monod`	Run as dedicated user (not root)
`WorkingDirectory=/home/monod`	Set process working directory
`ExecStart=...`	Command to start the node
`Restart=on-failure`	Auto-restart on crashes
`LimitNOFILE=65535`	Increase file descriptor limit
`ProtectSystem=strict`	Read-only system directories
`ReadWritePaths=/home/monod/.monod`	Allow 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-core/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

With Cosmovisor

Cosmovisor handles upgrades automatically when properly configured. See Upgrades.

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/.monod

Permission Issues with Data Directory

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

Solution:

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

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

# Verify
sudo -u monod ls -la /home/monod/.monod/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 ~/.monod/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 ~/.monod/data

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

# 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
monoctl peers update --network Sprintnet

# 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)

Cosmovisor Not Found (status=203/EXEC)

Symptom: status=203/EXEC or cosmovisor: command not found in systemd logs

Cause: The systemd service is trying to run Cosmovisor from a path where it doesn't exist. This commonly happens when:

Cosmovisor was installed via go install but the service references /usr/local/go/bin/cosmovisor (wrong path)
The monod user doesn't have access to where Cosmovisor is installed

Solution:

# Find where cosmovisor is installed
which cosmovisor
# Typical locations:
# - ~/go/bin/cosmovisor (user install)
# - /home/<user>/go/bin/cosmovisor (user install)

# Copy to system-wide location
sudo cp $(go env GOPATH)/bin/cosmovisor /usr/local/bin/

# Verify it works
/usr/local/bin/cosmovisor version

# Update systemd service to use correct path
sudo vim /etc/systemd/system/monod.service
# Change ExecStart line to:
# ExecStart=/usr/local/bin/cosmovisor run start --home /home/monod/.monod

# Reload and restart
sudo systemctl daemon-reload
sudo systemctl restart monod

# Check status
sudo systemctl status monod

Next Steps

After successful installation:

Deployment Modes - Understand host-native vs Docker
Mono Commander - Recommended operator tool
Join Network - Connect to a network
Configure Node - Set up peers
Monitoring - Set up observability

Prerequisites​

System Requirements​

Software Prerequisites​

Network Requirements​

Create Dedicated User (Recommended)​

Mono Commander (Recommended)​

Install Commander​

monod Binary​

Download Binary​

Build from Source​

Prerequisites​

Build​

Verify Installation​

Cosmovisor (Recommended)​

Install Cosmovisor​

Setup Directory Structure​

Environment Variables​

systemd Service Configuration​

Without Cosmovisor​

With Cosmovisor (Recommended for Production)​

Enable and Start Service​

systemd Unit File Explained​

Service Management Commands​

Verify Checksums​

Updating​

Manual Update​

With Cosmovisor​

Troubleshooting​

Permission Denied​

Command Not Found​

Wrong Architecture​

systemd Service Fails to Start​

Permission Issues with Data Directory​

Port Already in Use​

Out of Disk Space​

Sync Stuck or Very Slow​

SELinux Blocking Access (RHEL/CentOS)​

Cosmovisor Not Found (status=203/EXEC)​

Next Steps​

Prerequisites

System Requirements

Software Prerequisites

Network Requirements

Create Dedicated User (Recommended)

Mono Commander (Recommended)

Install Commander

monod Binary

Download Binary

Build from Source

Prerequisites

Build

Verify Installation

Cosmovisor (Recommended)

Install Cosmovisor

Setup Directory Structure

Environment Variables

systemd Service Configuration

Without Cosmovisor

With Cosmovisor (Recommended for Production)

Enable and Start Service

systemd Unit File Explained

Service Management Commands

Verify Checksums

Updating

Manual Update

With Cosmovisor

Troubleshooting

Permission Denied

Command Not Found

Wrong Architecture

systemd Service Fails to Start

Permission Issues with Data Directory

Port Already in Use

Out of Disk Space

Sync Stuck or Very Slow

SELinux Blocking Access (RHEL/CentOS)

Cosmovisor Not Found (status=203/EXEC)

Next Steps