Neko Master: a self-hosted traffic dashboard for OpenClash gateways

What Neko Master solves for OpenClash operators

OpenClash exposes traffic through its own interface, but that interface is built for control, not for looking back at what happened last week. Neko Master takes the position that the gateway already knows the answers and the missing piece is a queryable history. The project describes itself as a traffic analysis and visualization tool for local gateway environments, and the feature table lists real-time monitoring, trend analysis over 30min / 1h / 24h windows, per-domain traffic with associated IPs and connection counts, ASN and geo-location per IP, and traffic distribution per proxy node.

The audience is narrow on purpose. You need a running OpenClash backend to point it at, and the README's multi-backend feature is about monitoring several OpenClash instances at once rather than mixing vendors. The disclaimer is unusually direct about scope: the project provides no network access service, no proxy subscription and no cross-network connectivity, and all data comes from the user's own network environment. If you were looking for something that changes how traffic flows, this is the wrong repository. It reads traffic that already flows.

How the collector, the web app and the storage layer fit together

The repository is a pnpm workspace with turbo as the task runner, and the Dockerfile makes the split explicit. There are three build targets: packages/shared, apps/collector and apps/web. The collector is built first, then deployed with production dependencies only into a separate directory, and the web app is built as a Next.js standalone output. In the production image the collector lives under ./apps/collector and the web bundle under ./apps/web/.next/standalone.

At runtime the container exposes three ports. The Compose file maps WEB_PORT 3000, API_PORT 3001 and COLLECTOR_WS_PORT 3002 internally, and exposes them outward as WEB_EXTERNAL_PORT, API_EXTERNAL_PORT and WS_EXTERNAL_PORT. The front end reads those external port values at runtime, which is why the .env.example warns that NEXT_PUBLIC_WS_PORT is a build-time variable and therefore useless for a prebuilt image. The collector pushes data over WebSocket on 3002; when that route is missing, the README says the app falls back to HTTP polling automatically.

Storage defaults to SQLite at /app/data/stats.db. ClickHouse is optional and off by default: CH_ENABLED, CH_REQUIRED and CH_WRITE_ENABLED all default to 0. The Compose file carries a long list of ClickHouse tuning keys (batch limits, compare windows, timeouts) that only matter if you turn that path on. For a single gateway, the SQLite default is the honest choice; the ClickHouse branch exists for people whose retention needs outgrew a file.

Installing Neko Master with Docker Compose

The README recommends Docker Compose and gives two template scenarios. Scenario A exposes only port 3000, which is enough for a same-origin deployment where the front end reaches the API through the web server. The volumes mount ./data for the SQLite file and an optional ./geoip directory for local MMDB files, mounted read-only at /app/data/geoip.

services:
  neko-master:
    image: foru17/neko-master:latest
    container_name: neko-master
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
      - ./geoip:/app/data/geoip:ro
    environment:
      - NODE_ENV=production
      - DB_PATH=/app/data/stats.db
      - COOKIE_SECRET=${COOKIE_SECRET}

Scenario B adds the WebSocket port for deployments behind Nginx or a tunnel. The README describes this as the recommended shape when a reverse proxy is in front, because the live stream on 3002 is what gives you push updates instead of polling.

services:
  neko-master:
    image: foru17/neko-master:latest
    container_name: neko-master
    restart: unless-stopped
    ports:
      - "3000:3000"
      - "3002:3002"
    volumes:
      - ./data:/app/data
    environment:
      - NODE_ENV=production
      - DB_PATH=/app/data/stats.db
      - COOKIE_SECRET=${COOKIE_SECRET}

Generate the cookie secret before starting, because the README marks it as required in production and suggests at least a 32-byte random string. The .env.example gives the same instruction.

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

With the secret in place, start the stack and open the UI.

docker compose up -d

After that, the README says to open http://localhost:3000. The repository's own docker-compose.yml uses the same command but maps 3000, 3001 and 3002 by default, with the external ports driven by WEB_EXTERNAL_PORT, API_EXTERNAL_PORT and WS_EXTERNAL_PORT. If any of those are already taken, the .env.example tells you to copy .env.example to .env and change the three numbers rather than editing the Compose file. There is no separate first-run wizard documented; the README's First Use section is the next stop after the container is up.

Where Neko Master stops being the right tool

The dependency on OpenClash as the data source is the sharpest limit. The feature table names OpenClash specifically under multi-backend support, and nothing in the README claims compatibility with other gateway software. If your traffic passes through a different stack, the collector has nothing to talk to.

The second limit is deployment shape. The .env.example is explicit that CORS_ORIGIN defaults to rejecting all cross-origin requests, and that this is fine for the default Docker layout where the front end and API share an origin. The moment you split the dashboard and the collector across different domains or ports, you must set CORS_ORIGIN to a comma-separated allowlist, and the example shows that those origins then get credentialed cross-origin access. That is a deliberate posture, not an oversight, but it means a split deployment is a configuration task rather than a default.

The third is the fallback. The README states that if WebSocket is not routed, the app falls back to HTTP polling automatically. That keeps the dashboard working behind a proxy that does not upgrade connections, but the feature table advertises millisecond latency for the WebSocket path, so a misconfigured proxy silently changes the character of the product. Nothing in the README describes a rollback procedure for a bad upgrade, and the volumes are plain bind mounts, so backup discipline is on you.

Neko Master against a general-purpose metrics stack

The obvious alternative for someone who wants traffic history is a time-series stack: a Prometheus-style scraper plus Grafana. The difference is in what each one understands. Prometheus models numeric series with labels, and you build the meaning yourself; a domain with an associated IP list and a connection count is not a native concept there. Neko Master's collector already speaks the gateway's vocabulary, which is why the feature table can offer per-domain traffic with associated IPs and per-proxy distribution without a query language in between.

The trade is flexibility. With a general metrics stack you can correlate this gateway's numbers with anything else you already scrape, and retention and downsampling are a solved problem with well-known knobs. Neko Master's retention story is a SQLite file by default, or ClickHouse if you enable it. There is no plugin ecosystem documented in the README. If your question is "how does this gateway's traffic compare to my application latency," a general stack answers it and Neko Master does not. If your question is "which domains did this proxy node carry yesterday," Neko Master answers it without you writing a query.

Licence, maintenance and what an upgrade costs

Neko Master is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are kept. The README's disclaimer adds that the authors assume no responsibility for consequences of using the software and asks users to comply with applicable laws and regulations. That is a disclaimer, not a licence term, and it does not change what MIT grants. For a self-hosted internal dashboard the practical implication is that redistribution inside a company is allowed; the usual caveat about bundling the licence text still applies, and this is not legal advice.

The last push to the default branch was on 2026-08-03, and the most recent release in the list is agent-v1.4.5 on 2026-07-19, alongside v1.4.0 on the same day and v1.3.10 on 2026-07-04. The repository is not archived. That is a project with recent activity, and the changelog files (CHANGELOG.md and CHANGELOG.en.md) are where the upgrade notes live. Upgrading a Compose deployment means pulling a new image and recreating the container; the SQLite file in ./data is the state that has to survive, and the README does not document a migration or rollback path, so copying that directory before a pull is the only stated safeguard. The Dockerfile pins Node 22 and pnpm 9.15.9, so building from source ties you to those versions.

Editorial conclusion

Adopt Neko Master if you already run OpenClash and want per-domain and per-proxy traffic history without sending that data to a third party. Do not adopt it if you expect it to proxy or unblock anything: the README states it provides no network access service and collects only from your own environment. Before deploying, verify two things: that COOKIE_SECRET is set to at least 32 random bytes, and that you know which of the three ports (3000 web, 3001 API, 3002 WebSocket) your reverse proxy actually forwards, because the README notes that when WS is not routed the app falls back to HTTP polling.

Frequently asked questions

Official sources

1. foru17/neko-master on GitHub
2. Issues
3. License: MIT
4. README
5. Releases