MeshMonitor

Appearance

GitHub Stars

Getting Started ​

This guide will help you get MeshMonitor up and running quickly.

Interactive Docker Compose Configurator

Want a custom configuration generated for you? Try our Docker Compose Configurator - it generates a ready-to-use docker-compose.yml and .env file based on your specific setup (TCP, BLE, Serial, with or without reverse proxy, etc.).

Deployment Methods ​

MeshMonitor supports multiple deployment options to fit your infrastructure.

At a Glance ​

MethodPlatformUpdatingComplexitySupport
🐳 Docker ComposeAnydocker compose pull && up -d, or WatchtowerLowOfficial
🖥️ Desktop AppWindows / macOS❌ ManualVery LowOfficial
☸️ Kubernetes / HelmAny✅ Yes (image pull)HighOfficial
📦 Proxmox LXCProxmox VEmeshmonitor-updateLowCommunity
❄️ NixOS FlakeNixOS✅ Declarative rebuildMediumCommunity
🔧 Bare MetalLinux / macOS❌ ManualMediumCommunity

Which Should I Choose? ​

  • You want the smoothest update experience → Docker Compose. docker compose pull && docker compose up -d when you see the update banner, or add Watchtower for unattended updates.
  • You're on a single Windows or macOS machine and don't want to think about servers → Desktop App. Updates are manual (download a new installer), but setup is the simplest.
  • You're running on a Kubernetes cluster → Helm chart. Upgrades are an image: tag bump and a helm upgrade.
  • You're a Proxmox VE user → Proxmox LXC for a lightweight, native-feeling install. Updates are a single meshmonitor-update command.
  • You're on NixOS → NixOS Flake for fully declarative deployment. Upgrades happen on nixos-rebuild.
  • You want to run directly on the host with Node.js → Bare Metal. Best for development or custom integrations.

Update notifications work everywhere

MeshMonitor detects new releases and shows an "Update available" banner with copy-pasteable instructions for whichever platform you're on — Docker, LXC, Kubernetes, or bare metal. It never modifies its own deployment; see Updating MeshMonitor for the per-platform steps and an unattended-updates recipe using Watchtower.

Officially Supported ​

  • 🐳 Docker Compose (recommended) - Works on any platform with Docker

    • Easiest setup, with an optional Watchtower recipe for unattended updates
    • Full feature support
    • See Quick Start below

  • 🖥️ Desktop Application - Standalone app for Windows and macOS

  • ☸️ Kubernetes/Helm - Production-grade orchestration

Community Supported ​

The following deployment methods are contributed and supported by the community:

Prerequisites ​

Before you begin, ensure you have:

At least one mesh source ​

MeshMonitor can monitor Meshtastic, MeshCore, and MQTT all at once — you only need one of these to get started. More can be added later from Dashboard → Sources.

Meshtastic — any of:

  • A Meshtastic device connected to your network via IP (WiFi or Ethernet)
  • A Serial/USB device with the Serial Bridge
  • A Bluetooth device with the BLE Bridge
  • meshtasticd running as a virtual node

MeshCore — a MeshCore companion or repeater attached over USB or reachable over TCP. See MeshCore.

MQTT — an MQTT broker (yours or a public one) carrying mesh traffic, or just use MeshMonitor's embedded broker — no external broker required.

Deployment Platform ​

Choose one based on your deployment method:

  • Docker Compose: Docker and Docker Compose installed
  • Proxmox LXC: Proxmox VE 7.0+
  • Kubernetes: Kubernetes cluster with Helm 3+
  • NixOS: NixOS system
  • Bare Metal: Node.js 20+ and npm

Quick Start with Docker Compose ​

The fastest way to get started is using Docker Compose. This takes less than 60 seconds!

1. Create docker-compose.yml ​

Create a docker-compose.yml file with the following content:

yaml
services:
  meshmonitor:
    image: ghcr.io/yeraze/meshmonitor:latest
    container_name: meshmonitor
    ports:
      - "8080:3001"
    restart: unless-stopped
    volumes:
      - meshmonitor-data:/data
    environment:
      - MESHTASTIC_NODE_IP=192.168.1.100  # Seeds the first source on first boot; add more nodes from Dashboard → Sources
      - ALLOWED_ORIGINS=http://localhost:8080  # Required for CORS

volumes:
  meshmonitor-data:
    driver: local

Choosing an image tag

TagTrackCadenceWhen to use
:latestStable~weeklyDefault. Recommended for most users
:devRC / fast-track~dailyYou want the newest features immediately and accept RC stability
:<major>.<minor> e.g. :4.13Stable lineEach stable in that seriesRolling upgrades pinned to a minor version
:<version> e.g. :4.13.0PinnedNever (immutable)Full control over exactly which version runs

:dev can briefly lag behind :latest right after a stable release ships, until the next RC is published. See the FAQ for more details.

That's it! No need for SESSION_SECRET, COOKIE_SECURE, or other complex settings for basic usage.

2. Start MeshMonitor ​

bash
docker compose up -d

3. Access the Interface ​

Open your browser and navigate to:

http://localhost:8080

4. Login with Default Credentials ​

On first launch, MeshMonitor creates a default admin account:

  • Username: admin
  • Password: changeme

Important: After logging in, immediately:

  1. Click on your username in the top right
  2. Select "Change Password"
  3. Set a strong, unique password

5. Manage Sources (new in 4.0) ​

The MESHTASTIC_NODE_IP / MESHTASTIC_TCP_PORT values bootstrap MeshMonitor's first source on first boot. Everything after that — adding nodes, renaming sources, enabling Virtual Node, or switching connection type — happens in Dashboard → Sources.

Multi-Source

MeshMonitor 4.0 can talk to multiple nodes at once (TCP, Serial, BLE, MQTT, MeshCore). Each source has its own Virtual Node, auto-responder, scheduler, and permissions. See Multi-Source.

What Just Happened? ​

MeshMonitor's Quick Start is optimized for simple local/home use:

  • ✅ Works over HTTP (no HTTPS required)
  • ✅ No SESSION_SECRET needed (auto-generated with warning)
  • ✅ Secure cookies automatically disabled for HTTP
  • ✅ CSRF protection active
  • ✅ Rate limiting active (1000 requests/15min)
  • ✅ Perfect for personal/home deployments

This configuration is ideal for:

  • Personal/home network deployments
  • Behind a firewall on trusted networks
  • Local-only access (not exposed to the internet)
  • Quick testing and evaluation

Note: The Docker container runs in production mode but with sensible defaults for local use. For internet-facing deployments, see the Production Deployment Guide.

Optional Configuration ​

Change the Bootstrap Source Address ​

MESHTASTIC_NODE_IP only seeds the first source on initial install. To change where that first source points before the database is initialized, set a different IP:

bash
export MESHTASTIC_NODE_IP=192.168.5.25
docker compose up -d

After first boot, edit the source from Dashboard → Sources → Edit instead. Changing the env var post-bootstrap has no effect on an existing source.

Custom Timezone ​

yaml
environment:
  - MESHTASTIC_NODE_IP=192.168.1.100
  - TZ=Europe/London  # See: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Accessing from Different Devices/IPs ​

Important: MeshMonitor uses CORS protection to prevent unauthorized access. You must set ALLOWED_ORIGINS to match how you're accessing the application.

For localhost access (as shown in the basic example):

yaml
- ALLOWED_ORIGINS=http://localhost:8080

For access via server IP (e.g., http://192.168.1.50:8080):

yaml
environment:
  - MESHTASTIC_NODE_IP=192.168.1.100
  - ALLOWED_ORIGINS=http://192.168.1.50:8080  # Replace with your server's IP

For multiple access methods (localhost AND server IP):

yaml
- ALLOWED_ORIGINS=http://localhost:8080,http://192.168.1.50:8080

Additional examples:

yaml
# Multiple origins with hostname
- ALLOWED_ORIGINS=http://192.168.1.50:8080,http://meshmonitor.local:8080

# Allow all origins (not recommended, use for testing only)
- ALLOWED_ORIGINS=*

Production Deployment ​

For production deployments with HTTPS, reverse proxies, or public internet access, see:

⚠️ Critical: Required Environment Variables for HTTPS ​

When deploying with HTTPS and a reverse proxy, you MUST set:

bash
SESSION_SECRET=your-secure-random-string       # REQUIRED
TRUST_PROXY=true                                # REQUIRED
COOKIE_SECURE=true                              # REQUIRED
ALLOWED_ORIGINS=https://meshmonitor.example.com # REQUIRED!

Without ALLOWED_ORIGINS, you will get blank pages and CORS errors!

Key Differences in Production ​

  • SESSION_SECRET: Required, must be set to a secure random string
  • HTTPS: Strongly recommended for production
  • TRUST_PROXY=true: Required when behind reverse proxy (nginx, Traefik, Caddy)
  • COOKIE_SECURE=true: Required for HTTPS
  • ALLOWED_ORIGINS: CRITICAL - Must match your HTTPS domain, or frontend won't load
  • Rate limiting: Stricter (1000 requests/15min vs 10,000)

Using with Virtual or Physical Devices ​

These sections cover Meshtastic-specific setups. For MeshCore add a source from Dashboard → Sources (details); for MQTT enable the embedded broker or point a source at an external broker.

Virtual Nodes with meshtasticd ​

If you're using meshtasticd (the virtual Meshtastic node daemon) for testing without physical hardware:

bash
# Start meshtasticd in simulation mode (requires config.yaml)
docker run -d --name meshtasticd \
  -v ./config.yaml:/etc/meshtasticd/config.yaml:ro \
  -p 4403:4403 \
  meshtastic/meshtasticd:latest meshtasticd -s

# Then set the IP to localhost
export MESHTASTIC_NODE_IP=localhost
docker compose up -d

See the meshtasticd configuration guide for config.yaml examples and more details.

Serial/USB Devices ​

For Serial or USB-connected Meshtastic devices, use the Meshtastic Serial Bridge to expose your device on TCP port 4403.

Bluetooth Devices ​

For Bluetooth Low Energy (BLE) Meshtastic devices, use the MeshMonitor BLE Bridge to create a TCP-to-BLE gateway.

Next Steps ​

Now that you have MeshMonitor running:

Troubleshooting ​

For common issues and solutions, see the FAQ which covers:

  • 🚨 Blank white screen - CORS and ALLOWED_ORIGINS issues
  • 🔐 Can't login / Session logs out - Cookie security and TRUST_PROXY configuration
  • 📡 Cannot connect to node - Network connectivity troubleshooting
  • 🔄 Multiple nodes - How to run multiple MeshMonitor instances
  • 💾 Database issues - How to reset and back up your data
  • 👤 Password reset - Admin and user password management

Quick Fixes ​

Cannot connect to node:

bash
# Verify node is reachable
ping 192.168.1.100

# Check port 4403 is accessible
telnet 192.168.1.100 4403

Database errors:

bash
docker compose down
docker volume rm meshmonitor-meshmonitor-data
docker compose up -d

Docker permission errors:

bash
sudo usermod -aG docker $USER
# Log out and back in

Getting Help ​

If you run into issues:

Last updated: