A lightweight web interface for meshcore-cli, providing browser-based access to MeshCore mesh network.
mc-webui is a Flask-based web application that wraps meshcore-cli, eliminating the need for SSH/terminal access when using MeshCore chat on a LoRa device connected to a Debian VM via BLE or USB. Tested on Heltec V3 and Heltec V4.
- Mobile-first design - Responsive UI optimized for small screens
- Channel management - Create, join, share (QR code), and switch between encrypted channels
- Direct Messages (DM) - Private messaging with delivery status tracking
- Smart notifications - Unread message counters per channel with cross-device sync
- Contact management - Manual approval mode, filtering, protection, cleanup tools
- Contact map - View contacts with GPS coordinates on OpenStreetMap (Leaflet)
- Message archives - Automatic daily archiving with browse-by-date selector
- Interactive Console - Direct meshcli command execution via WebSocket
- @Mentions autocomplete - Type @ to see contact suggestions with fuzzy search
- Echo tracking - "Heard X repeats" with repeater IDs for sent messages, route path for incoming messages (persisted across restarts)
- PWA support - Browser notifications and installable app (experimental)
- Full offline support - Works without internet (local Bootstrap, icons, emoji picker)
For detailed feature documentation, see the User Guide.
1. Meshcore Device (tested on Heltec V4)
- Flash the device at https://flasher.meshcore.co.uk/. Choose the
Companion USBrole. - Configure the device with the Meshcore mobile app (from Google Play Store / App Store): Name, Location (optional), Preset
2. Linux Server
- Git installed
- Docker and Docker Compose installed (installation guide)
Important Notes:
- No meshcore-cli installation required on host - automatically installed inside Docker container
- No manual directory setup needed - all data stored in
./data/inside the project directory - meshcore-cli version 1.3.12+ is automatically installed for proper DM functionality
-
Clone the repository
cd ~ git clone https://github.com/MarekWo/mc-webui cd mc-webui
-
Create configuration file
cp .env.example .env
In most cases, no changes are needed! The defaults work automatically:
MC_SERIAL_PORT=auto- auto-detects your USB deviceMC_DEVICE_NAME=auto- auto-detects device name from meshcli
Optionally edit
.envto set your timezone:TZ=Europe/WarsawTroubleshooting: Multiple USB devices or detection fails
Check available serial devices:
ls /dev/serial/by-id/
If you see multiple devices, edit
.envand setMC_SERIAL_PORTexplicitly:MC_SERIAL_PORT=/dev/serial/by-id/usb-Espressif_Systems_heltec_...
-
Verify Serial Device Permissions (if needed)
sudo usermod -aG dialout $USER # Log out and log back in for changes to take effect
-
Build and run
python3 -m app.version freeze docker compose up -d --build
This will:
- Download base images (Python, Alpine Linux)
- Install meshcore-cli inside containers
- Create
./data/directory structure automatically - Start both containers (meshcore-bridge and mc-webui)
-
Verify installation
docker compose ps
Both containers should show
Upstatus. Check logs if needed:docker compose logs -f
-
Access the web interface
Open your browser and navigate to:
http://<your-server-ip>:5000To find your server IP:
hostname -I | awk '{print $1}' -
Initial Configuration (In Web UI)
- Main page loads with chat interface on "Public" channel
- Wait for initial sync (1-2 minutes)
- Optional: Enable manual contact approval in Contact Management
- View messages - Main page shows chat history with auto-refresh every 10 seconds
- Send messages - Type in the text field and press Enter (135 bytes for channels, 150 bytes for DM)
- Switch channels - Use the dropdown in navbar
- Direct Messages - Access via menu (☰) → "Direct Messages"
- Manage contacts - Access via menu (☰) → "Contact Management"
- Console - Access via menu (☰) → "Console" for direct meshcli commands
For complete usage instructions, see the User Guide.
The easiest way to update mc-webui:
cd ~/mc-webui
./scripts/update.shThe script automatically pulls changes, freezes the version, and rebuilds containers.
Optional: Create a global alias for quick updates
Add to your ~/.bashrc or ~/.zshrc:
alias mcupdate='~/mc-webui/scripts/update.sh'Then reload your shell (source ~/.bashrc) and update anytime with:
mcupdateIf you prefer to run commands manually:
cd ~/mc-webui
git pull
python3 -m app.version freeze
docker compose up -d --buildThe python3 -m app.version freeze command captures the current Git version (date + commit hash) for display in the app menu.
The dev branch contains new features that are still being tested:
cd ~/mc-webui
git checkout dev
./scripts/update.shTo return to the stable version:
cd ~/mc-webui
git checkout main
./scripts/update.shYou can enable one-click updates directly from the mc-webui menu. This requires installing a small webhook service on the host machine.
Install the updater service:
cd ~/mc-webui
sudo ./scripts/updater/install.shThe installer will:
- Create a systemd service
mc-webui-updater - Start a webhook server on port 5050 (localhost only)
- Enable automatic startup on boot
Usage:
- Click the refresh button (↻) next to the version in the menu
- If an update is available, an "Update" button appears
- Click "Update" to trigger the update remotely
- The app will automatically reload when the update completes
Useful commands:
# Check service status
systemctl status mc-webui-updater
# View logs
journalctl -u mc-webui-updater -f
# Uninstall
sudo ~/mc-webui/scripts/updater/install.sh --uninstallSecurity note: The webhook listens only on localhost. The Docker container connects to it via the Docker bridge network.
| Document | Description |
|---|---|
| User Guide | Complete feature documentation |
| Architecture | Technical details, API reference |
| Troubleshooting | Common issues and solutions |
| Docker Installation | How to install Docker on Debian/Ubuntu |
| Container Watchdog | Auto-restart for unhealthy containers |
- Environment Setup & Docker Architecture
- Backend Basics (REST API, message parsing, CLI wrapper)
- Frontend Chat View (Bootstrap UI, message display)
- Message Sending (Send form, reply functionality)
- Intelligent Auto-refresh (10s checks, UI updates only when needed)
- Contact Management (Cleanup modal with configurable threshold)
- Channel Management (Create, join, share via QR, delete with auto-cleanup)
- Public Channels (# prefix support, auto-key generation)
- Message Archiving (Daily archiving with browse-by-date selector)
- Smart Notifications (Unread counters per channel and total)
- Direct Messages (DM) - Private messaging with delivery status tracking
- Advanced Contact Management - Multi-page interface with sorting, filtering
- Message Content Enhancements - Mention badges, clickable URLs, image previews
- @Mentions Autocomplete - Type @ to get contact suggestions with fuzzy search
- PWA Notifications (Experimental) - Browser notifications and app badge counters
- Full Offline Support - Local Bootstrap libraries and Service Worker caching
- Interactive Console - Direct meshcli access via WebSocket with command history
- Contact Map - View contacts with GPS coordinates on OpenStreetMap (Leaflet)
- Echo Tracking - "Heard X repeats" badge for sent channel messages
- Performance Optimization - Frontend and backend improvements
- Enhanced Testing - Unit and integration tests
- Documentation Polish - API docs and usage guides
Important: This application is designed for trusted local networks only and has no authentication. Do not expose it to the internet without implementing proper security measures.
This is an open-source project. Contributions are welcome!
- All code, comments, and documentation must be in English
- Follow the existing code style
- Test your changes with real hardware if possible
If you appreciate what I am doing you can buy me a coffee :)
Thanks!
