What Is This?

This is a self-hosted Docker stack that brings together everything you need to run a MeshCore bot on your local network — with a friendly web interface for monitoring, control, and configuration. No command-line experience required after the initial setup.

The stack consists of five services that work together:

• Serial Bridge — shares your USB radio with all other services simultaneously
• MeshCore Bot — listens on the mesh, responds to commands, and logs all activity
• Bot Web Viewer — live dashboard showing contacts, mesh graph, stats, and more
• RemoteTerm — interactive terminal for sending commands directly to the radio
• Config Editor — point-and-click interface for all bot settings (no INI file editing)

Architecture

All services run as Docker containers on the same host and communicate over an internal Docker network:

Your MeshCore Radio (USB)
         │
   [serial-bridge]  — owns the USB port, broadcasts to TCP :5000
         │                    │
  [meshcore-bot]       [remoteterm]
   :8080 web UI         :8000 web UI
         │
  [config-editor]
   :8090 web UI

  [nginx dashboard]  :80  — landing page + API proxy for dashboard widgets

Quick Start

1. Plug your MeshCore radio into a USB port on the host machine.
2. Make sure /dev/ttyUSB0 (or your device path) is visible: ls /dev/ttyUSB*
3. Clone or copy this project to your server.
4. Open the Config Editor at http://<your-ip>:8090 and fill in at minimum:
   • Your Bot Name
   • Your Timezone (e.g. America/Chicago)
   • Your Latitude & Longitude (for weather and location features)
   • The Channels you want to monitor
5. Click Save Config then Restart Bot.
6. Check the Bot Web Viewer at :8080 — the uptime counter should be running.

Dashboard :80

The page you're reading right now. It provides a single entry point to the whole stack — live stats pulled from the bot, quick links to all three service UIs, and this documentation. Stats refresh automatically every 30 seconds.

Use the moon/sun icon in the top-right to switch between dark and light mode. Your preference is saved in the browser.

Bot Web Viewer :8080

The main monitoring interface for the MeshCore bot. Key tabs:

• Dashboard — real-time uptime, component health, and recent activity
• Contacts — every node the bot has heard, with signal strength, hops, and location
• Realtime — live stream of incoming mesh packets
• Mesh Graph — visual map of how nodes are connected
• Stats — 24h/7d/30d activity charts and top users
• Radio — device info and channel list

RemoteTerm :8000

A full-featured interactive terminal for MeshCore, built by jkingsman. Use it to:

• Send and receive direct messages
• Browse channel messages in real time
• Inspect raw packet data
• Manage contacts and channels on the device
• Run radio CLI commands interactively

Config Editor :8090

A point-and-click editor for the bot's config.ini file. Every setting has a description pulled from the config file itself, so you always know what you're changing.

• Toggle switches for true/false settings
• Dropdowns for fixed-choice settings like connection type
• Number spinners for timeouts, rates, and coordinates
• Save Config — writes directly to disk without restarting
• Restart Bot — applies changes that require a full restart

Serial Bridge internal :5000

A small Python service that owns /dev/ttyUSB0 and exposes it as a TCP server on port 5000 — internal to the Docker network only, never exposed to the host.

It works as a broadcast multiplexer:

• Every byte received from the radio is sent to all connected TCP clients
• Writes from any client are queued and sent to the radio one at a time

To check which clients are connected and whether the port is open:

docker logs serial-bridge

Configuration Overview

The bot is configured via bot/data/config.ini — an INI-format file divided into sections. You can edit it directly or use the Config Editor.

Connection

Controls how the bot physically connects to the MeshCore radio.

Bot Behavior

The main section — controls the bot's identity, location, rate limiting, and how it handles messages.

Identity

Location & Time

Rate Limiting

These settings prevent the bot from flooding the mesh network with too many messages.

Startup & Advertising

Contact Management

General

Channels

Banned Users

Localization

Admin Access Control

Certain commands (like !reload and !repeater) are restricted to admin users only.

Companion Purge

When the radio's contact list is nearly full, the bot can automatically remove contacts that haven't been heard from in a while.

Bot Commands

These commands can be sent to the bot over the mesh — in a monitored channel or via DM.

Troubleshooting

Dashboard shows "Bot Down?" instead of uptime

The bot web viewer can't find the bot's start time in the database. Check the bot is actually running:

docker ps
docker logs meshcore-bot --tail 30

If it's crashing on startup, the most common causes are:

• Serial bridge not ready yet — wait 5 seconds and the bot will auto-retry
• Config syntax error — open the Config Editor and check for obvious mistakes

Bot connects but "Radio Disconnected" shows in dashboard

The serial bridge started but lost the USB device. Check:

docker logs serial-bridge
ls /dev/ttyUSB*

If /dev/ttyUSB0 is gone, the USB device was unplugged or the kernel dropped it. Re-plug the radio and restart the serial bridge:

docker restart serial-bridge

Config Editor says "Restart Bot" but uptime doesn't reset

The Docker socket permission may be wrong. Check:

docker logs config-editor --tail 20

You can manually restart the bot with:

docker restart meshcore-bot

RemoteTerm shows "Connecting…" forever

RemoteTerm connects via the serial bridge. If the bridge is healthy but RemoteTerm can't connect:

docker restart remoteterm

If that doesn't help, restart the whole stack:

cd ~/meshcore && docker compose down && docker compose up -d