Repolode
Submit
foru17

foru17/neko-master

A self-hosted dashboard that visualizes and audits network traffic from Clash/Mihomo (OpenClash) and Surge gateways.

View on GitHub
Stars
4,215
Forks
270
Open issues
14
Last commit
12 days ago

What is it?

Neko Master is a web dashboard for watching traffic that passes through a gateway running Clash/Mihomo (including OpenClash) or Surge. It shows real-time traffic, trends over 30 minutes, 1 hour and 24 hours, and per-domain and per-IP views with associated IPs, connection counts, ASN and geolocation. It also breaks down traffic and connections by proxy node and rule chain.

The app runs as a Node.js collector with a Next.js frontend, stores statistics in SQLite by default, and can optionally dual-write to ClickHouse for large datasets and long-range queries. Real-time updates use WebSocket, falling back to HTTP polling when the WebSocket port is not reachable. It can monitor several gateway backends at once. For gateways on remote machines, a Go agent runs near the gateway and reports data to a central panel, since the panel does not connect to the gateway directly.

Deployment is through Docker Compose, Docker run, a setup script, or from source with pnpm. Access control is token-based, and IP geolocation can use an online API or local GeoLite2 MMDB files.

Key features

  • 01Real-time traffic monitoring over WebSocket with HTTP polling fallback
  • 02Traffic trends across 30-minute, 1-hour and 24-hour windows
  • 03Per-domain and per-IP analysis with ASN and geolocation
  • 04Traffic and connection statistics per proxy node
  • 05Support for multiple Clash/Mihomo and Surge gateway backends
  • 06Optional ClickHouse storage alongside the default SQLite

Use cases

  • Checking which domains and IPs a home OpenClash or Mihomo gateway is sending traffic to
  • Auditing traffic through Surge across several devices
  • Collecting data from remote OpenWrt or Linux gateways via the agent
  • Reviewing months of traffic history on ClickHouse when SQLite becomes slow

Quick start

  1. 1

    Generate a cookie secret for session persistence

    export COOKIE_SECRET="$(openssl rand -hex 32)"
  2. 2

    Start the container with Docker (minimal, port 3000 only)

    docker run -d --name neko-master -p 3000:3000 -v $(pwd)/data:/app/data -e COOKIE_SECRET="$COOKIE_SECRET" --restart unless-stopped foru17/neko-master:latest
  3. 3

    Open http://localhost:3000 in your browser to configure your gateway

Things to know

  • Real-time WebSocket updates require port 3002 to be reachable through your reverse proxy; otherwise it falls back to polling.
  • Surge data refreshes via HTTP polling with roughly a 2-second delay.
  • It is a monitoring dashboard for your own gateway and needs a running Clash/Mihomo or Surge gateway to be useful.

In collections

Diagrams, charts & animated visualizationsDashboards & business intelligence toolsData science courses & tools

Topics

#traffic-monitor#network-monitoring#dashboard#clash#mihomo#surge#openclash#data-visualization#visualization

FAQ

What is neko-master?
A self-hosted dashboard that visualizes and audits network traffic from Clash/Mihomo (OpenClash) and Surge gateways. Neko Master is a web dashboard for watching traffic that passes through a gateway running Clash/Mihomo (including OpenClash) or Surge. It shows real-time traffic, trends over 30 minutes, 1 hour and 24 hours, and per-domain and per-IP views with associated IPs, connection counts, ASN and geolocation. It also breaks down traffic and connections by proxy node and rule chain.
Is neko-master free to use? What license does it have?
neko-master is open source under the MIT license. Check the license terms before using it in commercial products.
Is neko-master still maintained?
Actively maintained. The last commit to neko-master was on Oct 10, 2026.
What can I use neko-master for?
Checking which domains and IPs a home OpenClash or Mihomo gateway is sending traffic to Auditing traffic through Surge across several devices Collecting data from remote OpenWrt or Linux gateways via the agent Reviewing months of traffic history on ClickHouse when SQLite becomes slow
How do I install neko-master?
Generate a cookie secret for session persistence: export COOKIE_SECRET="$(openssl rand -hex 32)" Start the container with Docker (minimal, port 3000 only): docker run -d --name neko-master -p 3000:3000 -v $(pwd)/data:/app/data -e COOKIE_SECRET="$COOKIE_SECRET" --restart unless-stopped foru17/neko-master:latest Open http://localhost:3000 in your browser to configure your gateway
Where can I get neko-master?
The source code and installation instructions are on GitHub: https://github.com/foru17/neko-master

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects