Stop Flying Blind: Neko Master Exposes Your Network Traffic

Stop Flying Blind: Neko Master Exposes Your Network Traffic

Your network gateway is a black box. Every day, terabytes of data flow through your OpenClash, Mihomo, or Surge setup—yet you have zero visibility into what actually travels through it. Which domains dominate your bandwidth? Where do your connections actually terminate? Are your proxy nodes performing, or silently dropping packets while you blame your ISP?

Here's the brutal truth: most developers and homelab operators are network-blind. They configure elaborate routing rules, then pray everything works. When latency spikes or speeds crater, they guess. They tweak. They suffer.

That ends now.

Meet Neko Master—a modern, elegant dashboard for network traffic visualization and analysis that transforms your local gateway from an opaque appliance into a transparent, auditable system. Built by foru17 and already pulling serious traction on GitHub, this isn't another bloated monitoring suite. It's precision-engineered for the modern gateway stack: Clash, Mihomo, Surge, and beyond.

Ready to finally see your network? Let's dive deep.

What Is Neko Master?

Neko Master (ねこ, "cat" in Japanese, pronounced /ˈneɪkoʊ/) is a lightweight analytics dashboard designed specifically for modern gateway environments. Like its namesake, it observes network traffic quietly and precisely—no noise, no bloat, just crystalline clarity.

Created by developer foru17, Neko Master addresses a critical gap in the network tooling ecosystem. Traditional monitoring solutions like Prometheus + Grafana or Nagios are built for infrastructure operators managing data centers, not developers optimizing their home lab or small office gateway. They're heavy, complex, and fundamentally mismatched for the Clash/Mihomo/Surge workflow.

Neko Master inverts this paradigm. It's built on a Node.js 22 + Next.js^{↗ Bright Coding Blog} 16 + React^{↗ Bright Coding Blog} 19 frontend stack, paired with a Fastify + WebSocket backend, delivering millisecond-latency real-time updates through a polished, PWA-ready interface. The architecture separates cleanly into three deployable units: a collector service that ingests gateway data, a web application for visualization, and an optional agent daemon for distributed multi-gateway deployments.

Why is it trending now? Three forces converge:

1. The gateway stack explosion: Clash/Mihomo adoption has skyrocketed as users demand fine-grained traffic control, but visibility tooling hasn't kept pace.
2. The homelab renaissance: More developers are self-hosting, and they expect modern UX standards—dark mode, PWA support, responsive design—not 1990s SNMP dashboards.
3. The privacy imperative: Neko Master operates entirely within your network. No cloud dependency, no telemetry, no data exfiltration. Your traffic stays yours.

With Docker^{↗ Bright Coding Blog} deployment measured in minutes, not hours, and a one-click setup script that auto-resolves port conflicts, Neko Master removes every friction point between "I should monitor this" and "I am monitoring this."

Key Features That Separate Neko Master from the Pack

Neko Master isn't a feature checklist—it's a carefully curated capability set that solves real problems. Here's what makes it exceptional:

Real-Time Monitoring with WebSocket Precision

Unlike polling-based dashboards that update every 30 seconds and miss micro-bursts, Neko Master uses WebSocket real-time collection with millisecond latency. Watch connections spawn and terminate as they happen. Spot anomalies the instant they appear. The system gracefully degrades to HTTP polling (~5 second intervals) if WebSocket routing isn't available, but the full experience demands that /_cm_ws path.

Multi-Dimensional Trend Analysis

Traffic isn't flat—it's temporal. Neko Master provides 30-minute, 1-hour, and 24-hour trend views that reveal patterns invisible in snapshot metrics. Is your bandwidth spike a daily cron job, a misconfigured application, or actual user demand? The timeline tells the story.

Domain-Centric Intelligence

Most tools show you IP addresses. Neko Master shows you domains—the human-meaningful unit of network consumption. Per-domain traffic volume, associated IPs, and connection counts reveal which services actually dominate your pipe. That "mystery traffic" consuming 40% of your bandwidth? It's not a mystery anymore.

IP Analysis with Geolocation & ASN Data

For the infrastructure-curious, Neko Master enriches every IP with ASN identification, geo-location mapping, and reverse domain association. Understand not just that traffic flows to a destination, but where that destination lives and who operates the network. Optional local MMDB lookup keeps this entirely offline.

Proxy Node Performance Transparency

Running multiple proxy nodes? Neko Master breaks down traffic distribution and connection counts per node, exposing which endpoints are saturated, which are underutilized, and which might be silently failing. Stop guessing about node health—know it.

Progressive Web App & Theming

Install Neko Master as a desktop application via PWA for native-like experience. Toggle between light, dark, and system themes without jarring visual discontinuities. The interface, built on Tailwind CSS^{↗ Bright Coding Blog} + shadcn/ui, feels like a modern SaaS product—not a sysadmin's afterthought.

Multi-Backend & Agent Architecture

Monitor multiple OpenClash instances simultaneously from a single pane. Or deploy the agent mode to collect from remote gateways—OpenWrt routers, Linux boxes, macOS machines—without exposing your panel to the internet. The agent initiates outbound connections only; your security posture stays tight.

Optional ClickHouse Scale-Out

For power users with massive datasets, Neko Master's dual-write SQLite + ClickHouse architecture handles hundreds of thousands of domain/IP entries with sub-second aggregation over multi-day ranges. Start with SQLite, graduate to ClickHouse when volume demands it—zero migration friction.

Use Cases: Where Neko Master Absolutely Shines

1. The Homelab Operator Optimizing Gateway Performance

You've built the perfect routing setup: Clash Premium with elaborate rule-sets, automatic node selection, and geo-IP routing. But users complain about "slow internet." Neko Master reveals the truth: your Singapore node is handling 80% of traffic while Tokyo sits idle, or a specific streaming domain is bypassing your optimized path entirely. Fix with data, not intuition.

2. The Remote Worker Auditing Corporate VPN Overlap

Working from home with corporate VPN + personal gateway simultaneously? Neko Master maps which traffic flows where, exposing dangerous split-tunnel misconfigurations where sensitive data leaks outside the VPN tunnel. Compliance isn't a checkbox—it's continuous verification.

3. The Multi-Site Small Business Administrator

Three locations, three gateways, one headache. Deploy Neko Master agents at each site, centralize monitoring in one dashboard. Compare traffic patterns across locations, identify bandwidth hogs per branch, and standardize proxy configurations based on actual usage data—not guesswork.

4. The Privacy-Conscious Developer Validating Self-Hosted Infrastructure

You moved off cloud services for privacy. But does your gateway actually respect your rules? Neko Master's domain analysis verifies that telemetry domains are blocked, that DNS queries resolve correctly, and that no traffic unexpectedly routes through unwanted jurisdictions. Trust but verify—visually.

5. The Performance Engineer Debugging Connection Latency

Intermittent latency spikes destroying your gaming or video conferencing? Neko Master's real-time connection tracking identifies pattern correlations: spikes coincide with specific domain connections, particular proxy nodes, or geographic regions. Root cause analysis becomes visual, not speculative.

Step-by-Step Installation & Setup Guide

Neko Master prioritizes operational simplicity. Choose your deployment path:

Option 1: Docker Compose (Recommended)

The repository provides two minimal templates for common scenarios.

Scenario A: Minimal deployment (Web UI only)

services:
  neko-master:
    image: foru17/neko-master:latest
    container_name: neko-master
    restart: unless-stopped
    ports:
      - "3000:3000" # Web UI only
    volumes:
      - ./data:/app/data
      # Local MMDB (optional, download files into ./geoip)
      - ./geoip:/app/data/geoip:ro
    environment:
      - NODE_ENV=production
      - DB_PATH=/app/data/stats.db
      - COOKIE_SECRET=${COOKIE_SECRET}

Create .env alongside your docker-compose.yml:

# Generate cryptographically secure cookie secret
COOKIE_SECRET=$(openssl rand -hex 32)

Launch:

docker compose up -d

Access at http://localhost:3000. WebSocket falls back to HTTP polling automatically.

Scenario B: Full real-time with reverse proxy

services:
  neko-master:
    image: foru17/neko-master:latest
    container_name: neko-master
    restart: unless-stopped
    ports:
      - "3000:3000"  # Web UI
      - "3002:3002"  # WebSocket for proxy/tunnel forwarding
    volumes:
      - ./data:/app/data
      - ./geoip:/app/data/geoip:ro
    environment:
      - NODE_ENV=production
      - DB_PATH=/app/data/stats.db
      - COOKIE_SECRET=${COOKIE_SECRET}

docker compose up -d

Option 2: Docker Run (Quick Single-Container)

# Generate fixed cookie secret for session persistence
export COOKIE_SECRET="$(openssl rand -hex 32)"

# Minimal deployment
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

# With WebSocket exposed for reverse proxy
docker run -d \
  --name neko-master \
  -p 3000:3000 \
  -p 3002:3002 \
  -v $(pwd)/data:/app/data \
  -e COOKIE_SECRET="$COOKIE_SECRET" \
  --restart unless-stopped \
  foru17/neko-master:latest

Option 3: One-Click Setup Script (Auto-Conflict Resolution)

# Using curl
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

# Or wget
wget -qO- https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

The script automatically downloads configuration, detects port conflicts, suggests alternatives, and starts services. Ideal for first-time deployment.

Option 4: Source Development Build

# Clone repository
git clone https://github.com/foru17/neko-master.git
cd neko-master

# Install dependencies
pnpm install

# Prepare collector environment
cp apps/collector/.env.example apps/collector/.env

# Start development services
pnpm dev

Access at http://localhost:3000. In source mode, collector listens on 3001/3002, web on 3000.

REAL Code Examples from Neko Master

Let's examine production-ready configurations extracted directly from the repository documentation.

Example 1: Production Docker Compose with ClickHouse Scale-Out

This configuration demonstrates Neko Master's advanced dual-write architecture for high-volume environments:

services:
  neko-master:
    image: foru17/neko-master:latest
    container_name: neko-master
    restart: unless-stopped
    ports:
      - "3000:3000"
      - "3002:3002"
    volumes:
      - ./data:/app/data
      - ./geoip:/app/data/geoip:ro
    environment:
      - NODE_ENV=production
      - DB_PATH=/app/data/stats.db
      - COOKIE_SECRET=${COOKIE_SECRET}
      # ClickHouse integration for high-volume analytics
      - CH_ENABLED=${CH_ENABLED:-1}
      - CH_WRITE_ENABLED=${CH_WRITE_ENABLED:-1}
      - STATS_QUERY_SOURCE=${STATS_QUERY_SOURCE:-auto}
      - CH_HOST=${CH_HOST:-clickhouse}
      - CH_PORT=${CH_PORT:-8123}
      - CH_DATABASE=${CH_DATABASE:-neko_master}
      - CH_USER=${CH_USER:-neko}
      - CH_PASSWORD=${CH_PASSWORD:-neko_master}
    networks:
      - neko-master-network

  clickhouse:
    image: clickhouse/clickhouse-server:24.8
    container_name: neko-master-clickhouse
    restart: unless-stopped
    profiles: ["clickhouse"]
    ports:
      - "${CH_EXTERNAL_HTTP_PORT:-8123}:8123"
      - "${CH_EXTERNAL_NATIVE_PORT:-9000}:9000"
    volumes:
      - ./data/clickhouse:/var/lib/clickhouse
    environment:
      - CLICKHOUSE_DB=${CH_DATABASE:-neko_master}
      - CLICKHOUSE_USER=${CH_USER:-neko}
      - CLICKHOUSE_PASSWORD=${CH_PASSWORD:-neko_master}
      - CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1
    networks:
      - neko-master-network
    healthcheck:
      test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1:8123/ping || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

networks:
  neko-master-network:
    driver: bridge

What's happening here: The neko-master service configures dual-write mode where traffic statistics simultaneously persist to SQLite (for configuration/metadata) and ClickHouse (for high-performance analytics). The STATS_QUERY_SOURCE=auto enables intelligent routing—recent data from ClickHouse, historical from SQLite during transition periods. The ClickHouse service uses a healthcheck to ensure availability before Neko Master attempts writes. The profiles: ["clickhouse"] gate means this service only starts when explicitly requested via docker compose --profile clickhouse up -d.

Example 2: Nginx Reverse Proxy with WebSocket Path Routing

Proper reverse proxy configuration is critical for real-time functionality. This production Nginx configuration handles both web and WebSocket traffic under unified domain:

server {
  listen 443 ssl http2;
  server_name neko.example.com;

  # Standard web traffic → Neko Master web UI (port 3000)
  location / {
    proxy_pass http://<neko-master-host>:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }

  # WebSocket traffic → Neko Master collector (port 3002)
  # MUST use ^~ for prefix matching to prevent regex location interference
  location ^~ /_cm_ws {
    proxy_pass http://<neko-master-host>:3002;
    proxy_http_version 1.1;
    # Critical: upgrade connection to WebSocket protocol
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # Extended timeouts for persistent WS connections
    proxy_read_timeout 86400;
    proxy_send_timeout 86400;
    # Disable buffering for real-time streaming
    proxy_buffering off;
  }
}

Critical implementation details: The ^~ /_cm_ws location modifier ensures this prefix match takes precedence over regex locations that might otherwise capture WebSocket upgrade requests incorrectly. The Upgrade and Connection headers negotiate the protocol switch from HTTP to WebSocket. Without proxy_buffering off, Nginx would batch real-time updates, destroying the millisecond-latency value proposition. The 86400-second timeouts accommodate long-lived connections without premature termination.

Example 3: Agent Deployment for Remote Gateway Collection

When your gateway lives on a separate device from your monitoring panel, the Neko Master agent bridges the gap securely:

# Clash/Mihomo gateway agent installation
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/apps/agent/install.sh \
  | env NEKO_SERVER='http://your-panel:3000' \
        NEKO_BACKEND_ID='1' \
        NEKO_BACKEND_TOKEN='ag_xxx' \
        NEKO_GATEWAY_TYPE='clash' \
        NEKO_GATEWAY_URL='http://127.0.0.1:9090' \
        sh

# Surge gateway agent installation (different gateway type, polling-based)
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/apps/agent/install.sh \
  | env NEKO_SERVER='http://your-panel:3000' \
        NEKO_BACKEND_ID='2' \
        NEKO_BACKEND_TOKEN='ag_yyy' \
        NEKO_GATEWAY_TYPE='surge' \
        NEKO_GATEWAY_URL='http://127.0.0.1:9091' \
        sh

Security architecture insight: Notice the agent initiates outbound connections to the panel (NEKO_SERVER), never accepting inbound requests. This zero-trust model means remote gateways behind NAT or firewalls require no port forwarding. The NEKO_BACKEND_TOKEN provides authentication without exposing gateway credentials to the central panel. Multiple agents can coexist on one host via distinct NEKO_INSTANCE_NAME values, each targeting different gateways—enabling consolidation of multiple remote sites into unified visibility.

Post-installation management uses the nekoagent CLI:

nekoagent list               # Enumerate all agent instances
nekoagent status <instance>  # Check operational state
nekoagent logs <instance>    # Stream live logs for debugging
nekoagent restart <instance> # Restart specific agent
nekoagent upgrade            # Global binary and CLI update

Example 4: Surge Gateway Integration Configuration

For Surge users, enabling the HTTP API unlocks Neko Master's analytics capabilities:

[General]
# Enable HTTP remote API on local interface
http-api = 127.0.0.1:9091
# TLS disabled for local trusted network (enable for remote)
http-api-tls = false
# Enable web dashboard for verification
http-api-web-dashboard = true

Protocol distinction: Surge operates via HTTP polling (approximately 2-second refresh intervals) rather than Clash/Mihomo's WebSocket streaming. This architectural difference means Surge backends exhibit slightly higher latency in Neko Master's real-time view, but gain complete rule chain visualization unavailable in other gateway types. The http-api-web-dashboard = true setting enables Surge's native dashboard for independent verification that the API responds correctly before Neko Master integration.

Advanced Usage & Best Practices

Cookie Secret Persistence

Always generate a fixed COOKIE_SECRET with openssl rand -hex 32. Auto-generated secrets invalidate sessions on container restart if data directories aren't persisted—frustrating and avoidable.

Gradual ClickHouse Migration

Don't rush to ClickHouse. Start with STATS_QUERY_SOURCE=sqlite even after enabling dual-write. Accumulate confidence in write reliability, then switch to auto or clickhouse for reads. The migration script ./scripts/ch-migrate-docker.sh handles historical backfill when you're ready.

Local MMDB for Privacy-First Geolocation

Download GeoLite2-City.mmdb, GeoLite2-ASN.mmdb, and optionally GeoLite2-Country.mmdb to ./geoip, mount read-only, and set GEOIP_LOOKUP_PROVIDER=local. Eliminates external API dependencies entirely.

Port Conflict Automation

Before manual .env editing, try the one-click script. It detects conflicts and suggests available ports automatically—saving diagnostic time.

Emergency Access Recovery

If authentication tokens are lost, FORCE_ACCESS_CONTROL_OFF=true provides temporary emergency access. Remove immediately after reset—this is a recovery hatch, not a configuration mode.

Showcase Mode for Public Demos

Enable SHOWCASE_SITE_MODE=true to restrict write operations while demonstrating functionality. Prevents accidental configuration changes during presentations.

Comparison with Alternatives

Verdict: Neko Master occupies a unique position—more powerful than built-in dashboards, more purpose-built than generic monitoring stacks, with deployment simplicity that respects your time.

FAQ: Your Questions Answered

Q: Can I run Neko Master with only port 3000 exposed?

A: Absolutely. Core functionality remains fully operational. Without WebSocket routing, the application automatically falls back to HTTP polling with approximately 5-second update intervals. For the premium real-time experience, route /_cm_ws to port 3002.

Q: Why do sessions disappear after container restart?

A: Two causes: (1) COOKIE_SECRET isn't fixed—generate with openssl rand -hex 32 and persist in environment; (2) Data directory isn't mounted to host storage. Both are required for session continuity.

Q: Which MMDB files do I need for offline geolocation?

A: Minimum: GeoLite2-City.mmdb and GeoLite2-ASN.mmdb. Optional: GeoLite2-Country.mmdb. Download from P3TERX/GeoLite.mmdb, place in ./geoip, mount as ./geoip:/app/data/geoip:ro.

Q: How does agent mode handle security?

A: Agents initiate outbound HTTPS/WebSocket connections to the panel—no inbound ports required. Each agent authenticates with unique tokens. Gateway credentials never leave the agent host. Panel never connects to gateways directly.

Q: What's the ClickHouse migration path for existing SQLite users?

A: Phase 1: Enable CH_ENABLED=1 and CH_WRITE_ENABLED=1 with STATS_QUERY_SOURCE=sqlite (observe writes). Phase 2: Switch to STATS_QUERY_SOURCE=auto or clickhouse. Phase 3 (optional): Run ./scripts/ch-migrate-docker.sh for historical backfill. Phase 4 (optional): Enable CH_ONLY_MODE=1.

Q: Can I monitor multiple gateways simultaneously?

A: Yes. Add multiple backends in Settings → Backends. Mix Clash, Mihomo, and Surge sources. Use agent mode for remote gateways, direct connection for local ones.

Q: Is Neko Master suitable for production enterprise deployment?

A: With ClickHouse enabled, proper secret management, reverse proxy TLS termination, and health monitoring—yes. The architecture supports horizontal read scaling and automatic failover to SQLite. Start conservative, expand as operational confidence grows.

Conclusion: See What You've Been Missing

Network traffic isn't abstract—it's the lifeblood of every digital experience you deliver and consume. Operating without visibility is like flying through fog: technically possible, unnecessarily dangerous, and eventually catastrophic.

Neko Master eliminates that fog. In minutes, not days, you transform from network-blind to network-omniscient. From guessing about performance to knowing precisely. From hoping your gateway configuration works to verifying it continuously.

The modern gateway stack deserves modern visibility. Neko Master delivers exactly that—elegant, efficient, and engineered for how developers actually work.

Deploy it today. Your network has stories to tell. Start listening.

⭐ Star Neko Master on GitHub | 🐳 Pull the Docker image | 📖 Read the architecture docs

Built with precision by foru17. If Neko Master illuminates your network, consider starring the repository and sharing your deployment experience.