MeshMonitor: A Single Dashboard for Meshtastic, MeshCore, and MQTT Networks

What MeshMonitor Actually Solves

MeshMonitor targets people who run off-grid mesh networks and need to see them from one place. The README names three network types: Meshtastic, MeshCore, and MQTT. Without such a tool, an operator might have to open separate interfaces for each radio node or MQTT broker. MeshMonitor aggregates those sources into a single web dashboard. The intended user is someone who manages a deployment of mesh nodes, possibly across multiple sites, and wants a unified view. It is not a radio configuration tool; it monitors. The project is written in TypeScript and uses React for the front end and Node.js for the back end. The theme is Catppuccin Mocha dark, which is a specific aesthetic choice that may appeal to some operators and look unfamiliar to others. The core value is consolidation: one dashboard, one set of credentials, one data store for all your mesh traffic.

How Data Flows Through the Application

The README does not give a full architecture diagram, but the visible pieces reveal the flow. On first boot, an environment variable like MESHTASTIC_NODE_IP seeds the first source. The user then manages additional sources from the Dashboard under a Sources section. Each source is a mesh node or MQTT endpoint that the application polls or connects to. The data lands in a database: SQLite, PostgreSQL, or MySQL. The choice of database is significant because it affects deployment complexity. SQLite works for a single instance, while PostgreSQL or MySQL suit larger setups or high availability. The application itself runs as a Node.js service, exposed on port 3001 inside the container, and the Docker example maps it to host port 8080. The front end is served by the same Node process, so there is no separate web server. The dashboard presents the aggregated data. The README mentions client IP resolution and audit logs, which implies the application records access events. That data also flows into the database. There is no mention of real-time push or WebSocket; the monitoring model appears to be request-response or periodic polling, though the material does not specify the interval.

Getting It Running with Docker or Helm

The quick start is a single docker-compose file. You create a file with a meshmonitor service, pull ghcr.io/yeraze/meshmonitor:latest, map port 8080 to 3001, and mount a volume for /data. The environment variable MESHTASTIC_NODE_IP seeds the first source. You run docker compose up -d and open http://localhost:8080. The default login is admin with password changeme, and the README tells you to change it after first login. For Kubernetes, the project provides a Helm chart. You add the repository with helm repo add meshmonitor https://meshmonitor.org/charts, then install with helm install meshmonitor meshmonitor/meshmonitor -f custom-values.yaml. The custom values file sets env.meshtasticNodeIp and env.meshtasticUseTls. The chart is also available locally at helm/meshmonitor, so you can install from a checkout. That dual path is useful for testing changes. The Docker image is published to ghcr.io, which is a standard registry. The README claims a 60-second setup, which is plausible for the Docker path if you already have Docker installed. The Helm path takes longer because you need a cluster.

Proxy Authentication and Its Sharp Edges

MeshMonitor supports authentication through reverse proxy headers. The README lists Cloudflare Access, oauth2-proxy, Authelia, and Traefik ForwardAuth as supported. This is a common pattern for SSO: the proxy authenticates the user and passes headers to the application. The application then trusts those headers. The configuration uses environment variables: PROXY_AUTH_ENABLED, PROXY_AUTH_AUTO_PROVISION, PROXY_AUTH_ADMIN_GROUPS, PROXY_AUTH_ADMIN_EMAILS, PROXY_AUTH_NORMAL_USER_GROUPS, and TRUST_PROXY. A critical security requirement is that MeshMonitor must not be directly accessible. The README says to use Docker networks, firewall rules, or a VPN. If the proxy is bypassed, anyone can forge headers. Another requirement is that TRUST_PROXY must be set to 1 or an appropriate hop count or subnet. As of v4.13, the default is false. If you forget it, client IP resolution, rate limiting, and audit logs will all show the proxy's IP instead of the real client. That breaks logging and rate limiting. The README also warns that email uniqueness is not enforced in the database schema. If two users share an email, the first match is used. That is a subtle failure mode that could cause one user to see another's data if the proxy does not guarantee unique emails.

JWT Claim Handling: Where Things Break

The README spends significant space on Cloudflare Access JWT subset tokens. Cloudflare Access application JWTs contain only a subset of identity claims, typically email, aud, iss, and sub. Custom OIDC claims, like Auth0 role claims, appear only if the IdP integration includes them. If the claim named in PROXY_AUTH_JWT_GROUPS_CLAIM is missing from the Cf-Access-Jwt-Assertion header, MeshMonitor sees empty groups, and group-based admin detection never triggers. The README advises decoding a real request JWT at jwt.io to verify the claim exists and its shape. It notes that Cloudflare often places custom claims under a custom object, for example custom["https://your-domain/roles"], while official examples may show a flatter layout. The fallback is to set PROXY_AUTH_ADMIN_EMAILS to an operator email allowlist. That is a concrete workaround. The README also describes JWT groups normalization: string arrays are used as-is, single strings are wrapped into an array, and role objects with a .name property have that name extracted. This handles Auth0 Post-Login Actions that emit role objects. All group matching is case-insensitive. This section is a warning: the proxy integration is not plug-and-play. You must inspect your actual tokens. The material does not provide a built-in debug endpoint, so the verification is manual.

The Normal-User Group Gate and Its Two-Layer Model

The README describes a two-layer access model. The reverse proxy provides URL-level access control, and MeshMonitor adds an application-layer check via PROXY_AUTH_NORMAL_USER_GROUPS. That variable is optional; if empty, all users are allowed. When set, it acts as a second gate. This is a defense-in-depth approach. The benefit is that even if the proxy configuration is too permissive, the application still restricts access based on group membership. The cost is configuration complexity: you need to maintain group names in both the proxy and the application. The README does not specify how group claims are passed for generic proxies, only that it supports header-based authentication. For Cloudflare Access, the JWT is in the Cf-Access-Jwt-Assertion header. For oauth2-proxy, it likely uses email and groups headers, but the README does not give exact header names. That omission is a gap. An operator must consult the documentation site or the source code to find the exact header names. The two-layer model is a sound idea, but it requires the operator to understand both layers. The README's warning about email uniqueness also applies here: if the proxy sends duplicate emails, the application may associate the wrong user with a session.

Limitations and Wrong Use Cases

The most obvious limitation is the security-sensitive configuration. The README repeatedly warns about TRUST_PROXY and direct access. If you run MeshMonitor without a reverse proxy, you must disable proxy auth and rely on the built-in login. That is fine for a small network, but the default admin password is a known value. Another limitation is the lack of email uniqueness in the schema. That is a data integrity issue that could cause authorization mix-ups. The JWT claim complexity is another limitation: it is not a set-and-forget feature. The README does not mention any rate limiting or alerting features beyond audit logs. If you need active alerting, like email or SMS notifications when a node goes offline, the material does not confirm that capability. The project is also heavy for a simple MQTT monitor. If you only need to watch a single MQTT topic, a small script or a dedicated MQTT dashboard would be simpler. MeshMonitor is designed for aggregation, not for a single source. The database requirement adds operational overhead, especially with PostgreSQL or MySQL. The Docker image is large, and the Node.js runtime consumes more memory than a static dashboard. For a battery-powered or low-resource edge device, this may be too much.

Alternatives and How They Differ

The README does not name competitors, but the mesh ecosystem has alternatives. For Meshtastic specifically, the official Meshtastic web client or the Meshtastic Android app provides direct node management. Those tools are client-side and do not aggregate multiple networks. MeshMonitor's difference is the server-side aggregation and multi-network support. For MQTT, a general-purpose tool like Eclipse Mosquitto with a web dashboard, or a Node-RED flow, can monitor topics. Those tools have no built-in mesh protocol awareness. MeshMonitor understands Meshtastic and MeshCore data structures, which means it can display node IDs, positions, and message metadata in a meaningful way. A generic MQTT dashboard would show raw payloads. Another alternative is a homegrown solution using Telegraf and Grafana. That gives you full control over metrics and alerts, but it requires significant development effort. MeshMonitor provides a ready-made dashboard with authentication and multi-database support. The trade-off is that you inherit the project's configuration assumptions, including the proxy auth model. If you want a lightweight, single-purpose tool, the alternatives are simpler. If you want a turnkey aggregator, MeshMonitor is the one that fits.

Maintenance, Licensing, and Upgrade Notes

The repository is active, with recent releases in August 2026, including release candidates v4.15.2-rc6, rc5, and rc4. The release cadence suggests ongoing development. The project is licensed under BSD-3-Clause, which is permissive. You can use, modify, and redistribute it, provided you retain the copyright notice. The README does not discuss upgrade procedures, but the Docker image tag 'latest' implies a simple pull and restart. The Helm chart likely supports upgrades via helm upgrade, though the README does not say. The documentation site at meshmonitor.org hosts configuration and development guides. The project uses Weblate for translations, which indicates a localization effort. The maintenance cost is moderate: you need to keep the Docker image updated, watch for release candidates, and verify that your proxy configuration still works after upgrades. The JWT handling may change between versions, so you should test after each upgrade. The README does not mention a migration path for the database schema, but with three supported databases, schema changes are likely. The BSD-3-Clause license gives you freedom, but it also means no warranty or support. You are responsible for your own deployment.

Editorial conclusion

Adopt MeshMonitor if you operate multiple off-grid mesh networks and need a single web dashboard with SQLite, PostgreSQL, or MySQL storage. It is also a good fit if you already use a reverse proxy and want SSO through Cloudflare Access or oauth2-proxy. Skip it if your network is purely MQTT and you need a lightweight tool, or if you cannot guarantee the proxy security requirements. Before deploying, verify your JWT claims structure, set TRUST_PROXY correctly, and change the default admin password. Also confirm that your proxy supplies unique email addresses, because the database does not enforce email uniqueness.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes