sview

A TUI for monitoring Cardano nodes, written in Rust.

⚠️ Important Disclaimer

This tool was entirely created using AI coding agents. While the code has been tested and reviewed, you should be aware of the following:

• Use at your own risk — This software is provided as-is. The developers are not responsible for any losses, damage, or issues arising from its use.
• Code review recommended — Before running this tool in a production environment, we strongly recommend having the code reviewed by qualified Rust developers familiar with Cardano infrastructure.
• Security considerations — The tool connects to your node's Prometheus metrics endpoint. Ensure your Prometheus port is not exposed to untrusted networks.
• Monitoring only — This tool is read-only and does not send commands to your node. However, information displayed comes from your node's metrics.
• Test thoroughly — Run sview in a non-critical environment first to ensure it works as expected for your setup.
• No warranty — This software comes with no warranty, express or implied. Use it only if you understand and accept these risks.

If you discover a security issue, please report it responsibly to the project maintainers.

---

Overview

sview is a terminal-based monitoring tool for Cardano nodes. It provides real-time metrics and status information by connecting to a node's Prometheus metrics endpoint.

Inspired by nview, sview is built from the ground up in Rust using ratatui for a modern, responsive TUI experience.

Features

• 📊 Real-time node metrics display with trend indicators (↑↓→)
• 📡 Block propagation stats (CDF: % of blocks within 1s/3s/5s)
• 🔑 OpCert validation for block producers (disk vs chain counter check)
• 🌐 Detailed peer list view with IP, RTT, direction, and geolocation
• 📈 Historical graphs view for key metrics over time
• 🔍 Auto-detection of node type and version from Prometheus metrics
• 🚦 Color-coded health indicators (sync status, peer count, memory)
• 📅 Epoch progress bar with time remaining countdown
• 🎨 8 color themes (5 dark + 3 light) with one-key cycling
• ⚡ Lightweight and fast — single binary, no runtime dependencies
• 🔧 Flexible configuration via CLI arguments, environment variables, or config file
• 🖥️ Multi-node monitoring — watch all your relays and block producer from one terminal
• 🐧 Cross-platform — Linux and macOS support

Installation

From Releases

Download the latest binary for your platform from the Releases page.

From Source

cargo install --git https://github.com/sandstonepool/sview

Build Locally

git clone https://github.com/sandstonepool/sview
cd sview
cargo build --release

Usage

Single Node (CLI)

# Default: connects to localhost:12798
sview

# Custom Prometheus endpoint
sview --prom-host 192.168.1.100 --prom-port 12798

# Set custom node name
sview --node-name "My Stake Pool"

# Using environment variables
PROM_HOST=192.168.1.100 NODE_NAME="My Stake Pool" sview

Multi-Node (Config File)

Create a config file at ~/.config/sview/config.toml:

[global]
network = "mainnet"
refresh_interval_secs = 2

[[nodes]]
name = "Relay 1"
host = "10.0.0.1"
port = 12798
role = "relay"

[[nodes]]
name = "Relay 2"
host = "10.0.0.2"
port = 12798
role = "relay"

[[nodes]]
name = "Block Producer"
host = "10.0.0.3"
port = 12798
role = "bp"

Then just run:

sview

Use Tab or number keys 1-9 to switch between nodes.

Keyboard Shortcuts

Key	Action
q, Esc	Quit
r	Force refresh metrics
?	Toggle help
t	Cycle color theme
p	Show peer connections
g	Show historical graphs
Tab	Next node (multi-node mode)
Shift+Tab	Previous node (multi-node mode)
1-9	Select node by number (multi-node mode)
← →	Switch between nodes (multi-node mode)

Color Themes

sview includes 8 color themes optimized for extended terminal viewing:

Dark themes (for dark terminals):

• Dark Default — Cool blues and cyans
• Dark Warm — Coral and peach tones
• Dark Purple — Purple and magenta pastels
• Dark Teal — Teal and mint greens
• Monokai — Classic Sublime Text colors

Light themes (for light terminals):

• Light Default — Soft blues on light background
• Light Warm — Peachy pastels
• Light Cool — Minty greens

Press t to cycle through themes. Your preference is saved to the config file.

Configuration

Configuration is loaded in the following order (later sources override earlier):

1. Config file (~/.config/sview/config.toml or --config <path>)
2. Environment variables
3. CLI arguments

If CLI arguments for --prom-host or --prom-port are provided, single-node mode is used regardless of config file.

CLI Arguments

Argument	Environment Variable	Description	Default
-n, --node-name	NODE_NAME	Display name for the node	Cardano Node
--network	CARDANO_NETWORK	Network name (mainnet, preprod, preview)	mainnet
--prom-host	PROM_HOST	Prometheus metrics host	127.0.0.1
-p, --prom-port	PROM_PORT	Prometheus metrics port	12798
--prom-timeout	PROM_TIMEOUT	Request timeout in seconds	3
-r, --refresh-interval	REFRESH_INTERVAL	Refresh interval in seconds	2
--history-length	HISTORY_LENGTH	Data points to keep for sparklines	60
--epoch-length	EPOCH_LENGTH	Epoch length in slots	432000
-c, --config	SVIEW_CONFIG	Path to config file	~/.config/sview/config.toml

Config File Format

# Global settings (apply to all nodes unless overridden)
[global]
network = "mainnet"              # Default network for all nodes
timeout_secs = 3                 # Request timeout
refresh_interval_secs = 2        # How often to poll metrics
history_length = 60              # Sparkline data points
epoch_length = 432000            # Slots per epoch (432000 for mainnet)

# Node definitions (one [[nodes]] block per node)
[[nodes]]
name = "My Relay"                # Display name (required)
host = "127.0.0.1"               # Prometheus host (default: 127.0.0.1)
port = 12798                     # Prometheus port (default: 12798)
role = "relay"                   # "relay" or "bp" (block-producer)
network = "preprod"              # Override global network for this node

Examples

# Monitor a remote node
sview --prom-host 10.0.0.5 -n "Relay 1"

# Slower refresh for low-bandwidth connections
sview --refresh-interval 5 --prom-timeout 10

# Monitor a testnet node (shorter epochs)
sview --network preprod --epoch-length 86400

# Use a custom config file
sview --config /path/to/my-config.toml

# Full example with all options
sview \
  --node-name "My Block Producer" \
  --network mainnet \
  --prom-host 192.168.1.100 \
  --prom-port 12798 \
  --refresh-interval 2 \
  --history-length 120

Health Indicators

sview uses color-coded indicators to show node health at a glance:

Color	Meaning
🟢 Green	Healthy — operating normally
🟡 Yellow	Warning — needs attention
🔴 Red	Critical — action required

Health thresholds:

• Sync Progress: Green ≥99.9%, Yellow ≥95%, Red <95%
• Connected Peers: Green ≥5, Yellow ≥2, Red <2
• Memory Usage: Green <12GB, Yellow <14GB, Red ≥14GB
• KES Remaining: Green ≥20 periods, Yellow ≥5, Red <5
• Tip Age: Green <60s, Yellow <120s, Red ≥120s

Requirements

Cardano Node Setup

Your Cardano node must have Prometheus metrics enabled. Add this to your config.json:

{
  "hasPrometheus": ["127.0.0.1", 12798],
  "TurnOnLogging": true,
  "TurnOnLogMetrics": true
}

Then restart your node:

systemctl restart cardano-node

Verify metrics are exposed:

curl http://localhost:12798/metrics | head -20

See METRICS_GUIDE.md for detailed troubleshooting.

System Requirements

• Terminal with Unicode support (minimum 80x24 recommended)
• Network access to Cardano node's Prometheus endpoint (default: localhost:12798)

Documentation

Comprehensive documentation is available in the docs/ folder:

• Getting Started — Quick start guide
• Configuration Guide — Config file and multi-node setup
• User Guide — Complete feature documentation
• Keyboard Shortcuts — Quick reference
• Troubleshooting — Common issues and solutions

License

Apache-2.0 — see LICENSE for details.

Acknowledgments

• nview — the original inspiration
• ratatui — the excellent Rust TUI library