NodeFlare/docs

NodeFlare

English | 简体中文

NodeFlare is a lightweight, self-hosted server monitoring panel: view server status in a web UI while a small agent collects and pushes telemetry. It supports live metrics, TCP/ICMP probing, Telegram alerts, remote command execution, TOTP two-factor authentication, theme customization, and SQLite / PostgreSQL backup, restore, and online migration.

Warning

NodeFlare is a self-hosted monitoring and control program and should only be deployed on systems you own or are authorized to manage. Deploying, accessing, or executing commands on unauthorized systems is at the deployer's own responsibility.

Documentation | Live Demo | FAQ | Releases

Screenshots

Features

• Live metrics: CPU, memory, and network speed sampled every second and uploaded in compressed batches every 3 seconds by default; slower metrics such as disks, GPU, and connection counts cached separately
• Latency probing: TCP and ICMP tasks assigned per node, with per-carrier (China Telecom / Mobile / Unicom) display
• Alerts: resource thresholds, offline, expiry, and traffic alerts pushed through Telegram with customizable message templates
• Theme store: built-in themes, one-click install from GitHub repositories, local ZIP upload, and per-theme settings
• Secure by default: TOTP two-factor authentication, Cloudflare Turnstile, login rate limiting, and session management; the server listens on 127.0.0.1 only, and the agent connects outbound with no inbound ports
• Data ownership: SQLite and PostgreSQL with online migration between them, one-click backup and restore, and automatic history cleanup by retention days

Quick Start

Install the server (downloads the latest release and registers a system service automatically).

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/elysia62/NodeFlare/main/install.sh | sudo sh

FreeBSD:

fetch -qo - https://raw.githubusercontent.com/elysia62/NodeFlare/main/install.sh | sudo sh

Windows PowerShell (Administrator):

Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/elysia62/NodeFlare/main/install.ps1 -OutFile "$env:TEMP\nodeflare-install.ps1"
Unblock-File "$env:TEMP\nodeflare-install.ps1"
& "$env:TEMP\nodeflare-install.ps1"

The first install asks for the admin username, password, listen port (default 2206), and database URL (SQLite by default). The server listens on 127.0.0.1:2206 by default — access it locally at http://127.0.0.1:2206/admin/login; use an HTTPS reverse proxy for external access.

Create a node on the Servers page of the admin panel and run the install command shown in its dialog to install the agent:

curl -fsSL https://raw.githubusercontent.com/elysia62/NodeFlare/main/agent/agent.sh \
  | sudo sh -s -- -e 'https://nodeflare.example.com' -t 'Agent Token'

Updating: re-run the install script. Config and data are preserved and a failed update rolls back automatically.

Tip

Script options, per-platform agent scripts, and uninstall steps are documented in Install the Server · Install the Agent · Uninstall.

Docker Deployment

Image: gxmandppx/nodeflare, available for amd64 / arm64. Both options require ./data/config.toml based on the example configuration, with ./data and the configuration file writable by container user 10001:10001.

Docker:

docker run -d --name nodeflare \
  --restart unless-stopped \
  -p 127.0.0.1:2206:2206 \
  -v "$PWD/data:/etc/nodeflare" \
  gxmandppx/nodeflare:latest

Docker Compose (save the following as compose.yaml):

services:
  nodeflare:
    image: gxmandppx/nodeflare:latest
    container_name: nodeflare
    restart: unless-stopped
    ports:
      - "127.0.0.1:2206:2206"
    volumes:
      - ./data:/etc/nodeflare

docker compose up -d

Documentation

Document	Description
Install the Server	One-line install, first-time setup, script options, updates
Install the Agent	Per-platform scripts and options
Uninstall	Uninstalling the server and agent, data cleanup
Configuration	Config options and a full example
Reverse Proxy	nginx / Caddy setup and trusted_proxies
Database & Backups	Backup / restore, SQLite ↔ PostgreSQL migration
Metrics & Sampling	Sampling rates and memory accounting
Alerts & Notifications	Threshold, offline, expiry, and traffic alerts
Theme Development	Theme package layout and data API
FAQ	Troubleshooting and frequently asked questions
Development Setup	Local development, tests, and builds

Development

git clone https://github.com/elysia62/NodeFlare.git
cd NodeFlare
bun install --frozen-lockfile
cp backend/config.example.toml backend/config.toml
./dev.sh

dev.sh builds the frontend and starts the backend with cargo run. Tests, builds, and the repository layout are described in Development Setup and Repository Layout.

License

MIT