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

Public dashboard · Live Demo

Admin panel

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

Deploy NodeFlare with Docker or Docker Compose. The gxmandppx/nodeflare image supports amd64 / arm64 and stores configuration and data in /etc/nodeflare on the host.

Before the first start, prepare the configuration file and allow the container to write to the data directory:

sudo mkdir -p /etc/nodeflare
sudo curl -fsSL https://raw.githubusercontent.com/elysia62/NodeFlare/main/docker/config.example.toml -o /etc/nodeflare/config.toml
# Edit /etc/nodeflare/config.toml and set the administrator username and password
sudo chown -R 10001:10001 /etc/nodeflare

Docker:

docker run -d --name nodeflare \
  --restart unless-stopped \
  -p 2206:2206 \
  -v /etc/nodeflare:/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:
      - "2206:2206"
    volumes:
      - /etc/nodeflare:/etc/nodeflare

docker compose up -d

Then open http://<server-address>:2206/admin/login. The panel does not serve HTTPS, so to expose it externally publish the port on loopback (-p 127.0.0.1:2206:2206) and put an HTTPS reverse proxy in front. Updates, logs, and uninstall: Docker Deployment.

Documentation

Document	Description
Install the Server	One-line install, first-time setup, script options, updates
Docker Deployment	Official image, Compose setup, and data persistence
Install the Agent	Per-platform scripts and options
Platforms & Paths	Supported systems and architectures, default paths and logs
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