Skip to content

Configuration

Jump to bottom
Slofi edited this page Mar 21, 2026 · 2 revisions

Configuration

OverMesh is configured via config.json in the app directory. If it doesn't exist yet, copy the template:

cp config.example.json config.json

Most settings can also be changed through the UI (Settings tab) — they write back to config.json automatically. The only thing you really need to set manually is the node port, and only on first run.

Full example

{
  "nodes": [
    {
      "id": "node_XXXXXXXXX",
      "name": "MyNode",
      "port": "/dev/ttyUSB0",
      "enabled": true
    }
  ],
  "port": 8081,
  "app": {
    "zoom": 100,
    "accent_color": "#4ade80"
  },
  "sense_passive": false,
  "sense_active_auto": false
}

Reference

nodes[]

Each entry is one physical Meshtastic node connected via USB.

Key Description Required
id Internal identifier — set automatically, don't change it Auto
name Display name shown in the header and UI Yes
port Serial port (/dev/ttyUSB0, /dev/ttyACM0, COM3...) Yes
enabled Set to false to skip this node on startup without removing it Optional
usb_serial USB hardware serial number — set automatically after first connect for plug-and-play detection Auto
msgs_db Message database filename — set automatically Auto

You can add and manage nodes through Settings → Radios in the UI. You only need to edit this manually for the first node.

Top-level keys

Key Description Default
port Port the web server listens on 8081
host IP address Flask binds to; set to 127.0.0.1 to restrict to localhost 0.0.0.0
sense_passive Start passive Sense listening on launch false
sense_active_auto Start periodic active Sense scanning on launch false

app

Key Description Default
zoom UI zoom level, 75–125% 100
accent_color Hex color for the UI accent; all shades auto-derived #4ade80
sense_cooldown Seconds between active Sense runs 180

Environment variables

For containers or non-standard deployments, these override the corresponding config values. If none are set, the behaviour is identical to a plain python3 app.py run.

Variable Overrides Description
OVERMESH_CONFIG — Full path to config.json
OVERMESH_DATA_DIR — Directory for all databases (overmesh_prefs.db, per-radio message DBs)
OVERMESH_HOST host in config Flask bind address
OVERMESH_PORT port in config Flask port

Example (Docker or systemd override):

OVERMESH_CONFIG=/data/config.json
OVERMESH_DATA_DIR=/data
OVERMESH_HOST=0.0.0.0
OVERMESH_PORT=8081

Notes

  • config.json is written atomically (temp file + rename) — a crash during save won't corrupt it
  • The file is not tracked by git (it's in .gitignore); your personal config won't end up in a commit
  • Bot settings are stored separately in bot_config_<radio_id>.json — see Bot

Clone this wiki locally