Klever Node Hub

What is the Node Hub?

Klever Node Hub is a free, open-source, self-hosted web dashboard for Klever validator operators. It manages and monitors all your nodes across multiple servers, without SSH sessions and manual scripts. It has two parts:

• Dashboard: a web application you run on one of your servers. This is your control centre, reachable from any browser.
• Agent: a lightweight program on every server that hosts Klever nodes. It talks to the dashboard over an encrypted WebSocket connection.

What it replaces

What it is not

• Not a cloud service: everything runs on your own infrastructure.
• Not a wallet: it does not handle KLV or transactions.
• Not a staking service: it manages the infrastructure, not the staking itself.
• Your node servers need no extra open ports: the agents connect outbound to the dashboard.

Architecture

• The dashboard is the brain: it serves the web interface, stores its data in SQLite and orchestrates all actions.
• The agents are the hands: they sit on each node server, run the Docker commands, collect metrics and stream logs.
• Dashboard and agents authenticate each other with mTLS (mutual TLS with Ed25519 certificates). No SSH keys are stored and no passwords are shared.
• On first start the dashboard creates its own certificate authority. Every agent that registers receives a signed client certificate.

Install the dashboard

The dashboard runs on one of your servers (or a separate management server). Browsers and all agents must be able to reach it on port 9443.

Option A: Docker (recommended)

docker run -d \
  -p 9443:9443 \
  -v klever-data:/root/.klever-node-hub \
  --name klever-node-hub \
  ctjaeger/klever-node-hub:latest \
  --domain your-server.example.com

The --domain flag is optional. You only need it for passkey login, because WebAuthn requires a domain. Password login works with a plain IP address.

Option B: Binary

wget https://github.com/CTJaeger/KleverNodeHub/releases/latest/download/klever-node-hub-linux-amd64
chmod +x klever-node-hub-linux-amd64
./klever-node-hub-linux-amd64 --domain your-server.example.com

For ARM servers use klever-node-hub-linux-arm64. Every release also contains a checksums.txt with SHA-256 sums, and builds for macOS and Windows.

Option C: Build from source

You need Go 1.26 or newer.

git clone https://github.com/CTJaeger/KleverNodeHub.git
cd KleverNodeHub
make build-linux
scp bin/klever-node-hub-linux user@your-server:/opt/klever/klever-node-hub
./klever-node-hub --domain your-server.example.com

Dashboard flags

After the start the dashboard creates a self-signed certificate and is available at https://your-server:9443. Your browser will warn about the certificate until you put a reverse proxy in front (next section).

Trusted HTTPS with a reverse proxy

With the built-in self-signed certificate, browsers show a warning and a phone will not offer to install the dashboard as an app (a trusted certificate is needed for that). Put a reverse proxy with a Let's Encrypt certificate in front of the dashboard.

Browsers ──HTTPS:443──▶ Reverse proxy ──HTTPS:9443──▶ Dashboard
Agents   ──mTLS:9443─────────────────────────────▶ Dashboard

Prerequisites: a domain pointing to your server, ports 80 and 443 open, and Certbot with the plugin for your web server. The --domain flag of the dashboard must match the domain you use in the proxy.

Example: Apache

sudo apt install certbot python3-certbot-apache
sudo a2enmod proxy proxy_http proxy_wstunnel ssl rewrite headers
sudo systemctl restart apache2
sudo certbot certonly --apache -d your-domain.example.com

Create /etc/apache2/sites-available/klever-node-hub.conf:

<VirtualHost *:80>
    ServerName your-domain.example.com
    RewriteEngine On
    RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L]
</VirtualHost>

<VirtualHost *:443>
    ServerName your-domain.example.com

    SSLEngine on
    SSLProtocol -all +TLSv1.2 +TLSv1.3
    SSLCertificateFile    /etc/letsencrypt/live/your-domain.example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/your-domain.example.com/privkey.pem

    # Proxy to the dashboard (self-signed backend certificate)
    ProxyPreserveHost On
    SSLProxyEngine On
    SSLProxyVerify none
    SSLProxyCheckPeerCN off
    SSLProxyCheckPeerName off

    # The dashboard uses the forwarded protocol and client address for rate limiting and lockout
    RequestHeader set X-Forwarded-Proto "https"

    # WebSocket support (live metrics and log streaming)
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteRule ^/(.*)$ https://127.0.0.1:9443/$1 [P,L]

    ProxyPass / https://127.0.0.1:9443/
    ProxyPassReverse / https://127.0.0.1:9443/
</VirtualHost>

sudo a2ensite klever-node-hub.conf
sudo apache2ctl configtest
sudo systemctl reload apache2

Certbot renews the certificate automatically. Check it with sudo certbot renew --dry-run.

Configurations for Nginx and Caddy are in the reverse proxy guide in the repository.

Install the agents

Every server that runs Klever nodes needs an agent. It connects outbound to your dashboard, so the node server needs no extra open port. Repeat these steps for each server; a token works only once.

1. Generate a registration token Open the dashboard, click Add Server, then Generate Token and copy the install command shown. The token is valid for one hour.
2. Run the install command on the node server Option A, the install script (recommended):

   curl -sSL https://raw.githubusercontent.com/CTJaeger/KleverNodeHub/main/scripts/install-agent.sh \
     | sudo bash -s -- --token <YOUR_TOKEN> --dashboard https://<DASHBOARD_IP>:9443

   The script installs Docker if needed, downloads the right agent for your architecture (amd64 or arm64), registers it with the token, creates a klever-agent systemd service, starts it and discovers the Klever nodes that already run on the server.
3. See the server appear As soon as the agent connects, the server shows up in the dashboard together with its nodes.

Option B: Docker

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --name klever-agent \
  ctjaeger/klever-agent:latest \
  --dashboard-url https://<DASHBOARD_IP>:9443 \
  --register-token <YOUR_TOKEN>

Option C: Manual binary

wget https://github.com/CTJaeger/KleverNodeHub/releases/latest/download/klever-agent-linux-amd64
chmod +x klever-agent-linux-amd64
./klever-agent-linux-amd64 --dashboard-url https://<DASHBOARD_IP>:9443 --register-token <YOUR_TOKEN>

Agent flags

After registration the agent keeps its certificate and reconnects by itself after a restart, no token needed.

First login and setup wizard

When you open https://your-server:9443 for the first time, the setup wizard starts.

1. Set a passwordChoose a strong one (at least 8 characters). It is your main login.
2. Register a passkey (optional)Log in with Face ID, Touch ID, Windows Hello or a hardware key such as a YubiKey. This needs a domain (--domain).
3. Save your recovery codesThe wizard creates 8 single-use codes. They are your way back in if you lose the password and all passkeys. Keep them safe.
4. Link your Klever wallet (optional)With the Klever Extension in your browser you can log in with your wallet. The dashboard checks ownership with a signature challenge.

If the codes get lost, start the dashboard once with --reset-recovery-codes to create new ones.

The dashboard at a glance

The dashboard is mobile-first and an installable progressive web app: add it to your phone's home screen and it behaves like a native app, with push notifications.

Batch operations

Select several nodes with the checkboxes on the overview page and start, stop, restart or upgrade them together. Batch upgrades run one node after the other so your quorum is kept.

Provision new nodes

You can set up a brand new Klever node from the dashboard, no SSH needed.

1. Open the serverGo to the detail page of the server and click Provision Node.
2. Choose the optionsNode name (or several nodes in one run, with automatically increasing REST API ports), Main or Fallback role, the network, and the sync mode.
3. StartClick Provision and follow the progress live.

The agent runs a preflight check (Docker, disk space, connectivity), pulls the Klever Docker image, creates the folders, downloads the initial configuration from the official Klever servers, creates and starts the container and finally verifies that the node answers. If a step fails, the agent cleans up.

Sync modes

Chain DB restore

For an existing node you can replace the chain database with the official full-node snapshot. The snapshot is streamed straight to disk after a disk-space check, and the previous database is kept for a rollback. This is how you turn a fast-bootstrapped node into a full archival node, for example for indexers.

Configuration and keys

Edit config files remotely

Open a node, go to Config, pick a file and edit it. Every save creates a backup of the previous version, and you can restore any backup with one click.

Push to several nodes

Edit a file on one node, click Push to Other Nodes, choose the target nodes and confirm. The Batch Config tool changes one parameter across all nodes at once, shows the current value of each node side by side and can restart the nodes afterwards.

Config upgrade

When you upgrade to a new image, the dashboard can fetch a fresh configuration from the official Klever servers, keep a versioned backup of your current one and apply the new one.

Validator keys

• Generate: creates a new BLS key inside the node's container and shows the public key.
• Import: paste an existing PEM file; it is written to the node's key folder.
• Export: shows or downloads the PEM, for backup or migration.
• Key operations create backups automatically.

Upgrades and downgrades

1. Pick the versionOpen the node and click Upgrade. The Docker image tags come from Docker Hub (cached for 15 minutes). An indicator shows which nodes are not on the latest version, and stable releases are ranked above release candidates.
2. ConfirmThe agent pulls the image, stops the container, creates a new one with the same settings and the new image, starts it and checks that it runs.
3. RollbackIf the upgrade fails, the agent returns to the previous image. To go back later, use Downgrade and pick an older tag.

Batch upgrades run sequentially to keep the quorum, optionally refreshing the configuration at the same time.

Monitoring and alerts

Metrics

The dashboard collects server metrics (CPU, memory, disk, network) and Klever node metrics from /node/status (76 values, including nonce, sync state, epoch, peers, consensus participation, TPS and transaction pool load) regularly from every node.

A daily background job condenses the recent data into the archive and removes old records. The charts are drawn with a small built-in chart library, without external dependencies.

Alert rules

The alert engine checks all rules every 15 seconds. A condition that holds for the configured time fires an alert; when the condition clears, the alert resolves.

Nonce stall detection is the most important alert for validators: if a node has not moved its nonce for 16 seconds or more, it has produced or finalized nothing for four slot cycles, and a critical alert fires immediately.

• Custom rules: on the Alerts page, change threshold, cooldown, duration and the notification channels per rule.
• History: every firing and resolution is logged with time, severity, node or server, notified channels and resolution time.
• Acknowledge: silences an active alert without resolving it.
• Maintenance aware: nodes you stop from the dashboard count as maintenance and do not fire offline alerts; this ends automatically once they run again.
• Version performance: flags a new node version that processes blocks measurably slower, with a before and after report per node.

Tools

Notifications

Set up a channel

1. Open the settingsGo to Settings → Notifications and click Add Channel.
2. Enter the access dataTelegram: bot token (from @BotFather) and chat ID. Pushover: user key and API token. Webhook: URL and optional headers. Web Push: switch it on and allow notifications in the browser.
3. Test and saveUse the Test button to check that a message arrives.

Each channel can be filtered by severity (info, warning, critical) and by alert type (node_down, nonce_stall, resource, metric, resolved). For example: all critical alerts to Telegram, but only nonce stalls to Pushover. A history of all sent notifications is under Settings → Notifications → History.

Updating agents and dashboard

Agents

Agents are updated from the dashboard, no SSH needed. Open Agent Update in the sidebar, pick a version from the list (it comes from the GitHub releases) and download it. The dashboard only downloads the builds your servers need. Then select the agents in the table, choose the target version and click Update.

Each agent shows its progress (waiting, updating, restarting, done or failed). The agent checks the SHA-256 checksum, keeps a backup of its current program, replaces it atomically and restarts. The dashboard waits up to 15 seconds for the agent to come back with the new version. To roll back, update to an earlier version from the same list. You can also restart an agent from the dashboard without touching the running nodes.

Dashboard

The dashboard checks for updates itself. With the Docker socket mounted, Update Now swaps the container cleanly and can roll back. Without it, the dashboard shows the docker pull command to run. The binary version replaces itself and restarts.

Security

Because the agents only run a fixed set of commands, a compromised dashboard still cannot run arbitrary commands on your node servers.

The code is open source under the MIT license. Security follows Kerckhoffs's principle: knowing the source code does not help an attacker without the keys. Report vulnerabilities through GitHub's private vulnerability reporting, not in public issues.

FAQ

Do I need to open ports on my node servers?

No. The agent connects outbound to the dashboard. Only the dashboard needs an open port (9443 by default), and agents must be able to reach it.

Does it work with nodes I already run?

Yes. When you install the agent on a server that already runs Klever nodes, it discovers all kleverapp/klever-go containers and they appear in the dashboard right away.

What happens to my nodes if the dashboard goes down?

They keep running. The dashboard is a management layer and does not affect node operation. When it is back, the agents reconnect automatically.

Can several people use it?

Currently there is a single admin account. Several people can be logged in at the same time with the same credentials.

Which architectures are supported?

linux/amd64 (standard servers) and linux/arm64 (for example Raspberry Pi, Ampere or Graviton servers).

Is there a mobile app?

The dashboard is a progressive web app. Install it from your phone's browser to the home screen; it works like a native app, including push notifications.

How much does the agent use?

Very little: typically under 20 MB of memory and negligible CPU. It is a single Go program without dependencies.

Where is the data stored?

The dashboard keeps a SQLite database in ~/.klever-node-hub/ (change it with --data-dir). The agent keeps its certificate in ~/.klever-agent/ (change it with --config-dir).

Does it work with testnet nodes?

Yes. It works with mainnet and testnet nodes; you choose the network when you provision a node.