Home Getting Started Configuration Reference

Configuration Reference

Getting Started config reference .mesh-dash_config settings jwt secret serial tcp ble webserial mqtt meshcore history community c2 scheduler hot-reload restart docker

Every key in .mesh-dash_config (59 documented keys), defaults, types, hot-reload vs restart behaviour, MQTT/MeshCore per-slot configs, internal constants, and file format.

MeshDash reads configuration from data/.mesh-dash_config on startup. Format: KEY=VALUE one per line, # comments. All values are coerced to their correct types at load time. Docker users must volume-mount the data/ directory — R2.x installs have their config file auto-migrated from the app root to data/ on first R3.0 boot.

Keys marked 🟢 Hot are applied immediately. Keys marked 🔴 Restart require a server restart. The Settings UI shows which keys changed and prompts for restart when needed.

Primary Radio Connection (node_0)

MESHTASTIC_CONNECTION_TYPE

🔴 Restart. Default: SERIAL. One of: SERIAL, TCP, BLE, WEBSERIAL, MQTT.

MESHTASTIC_HOST

🔴 Restart. Default: 192.168.0.0. IP or hostname for TCP connections.

MESHTASTIC_PORT

🔴 Restart. Default: 4403. TCP port for network connections.

MESHTASTIC_SERIAL_PORT

🔴 Restart. Default: (empty). Device path: /dev/ttyACM0, COM3. Only used when type is SERIAL.

MESHTASTIC_BLE_MAC

🔴 Restart. Default: (empty). MAC address: AA:BB:CC:11:22:33. Only used when type is BLE.

Web Server & Auth

WEBSERVER_HOST

🔴 Restart. Default: 0.0.0.0. Network interface to bind to.

WEBSERVER_PORT

🟢 Hot. Default: 8181. Main dashboard HTTP port.

NETWORK_WEBSERVER_PORT

🔴 Restart. Default: 8181. Analyzer port (currently mirrors main port).

AUTH_SECRET_KEY

🟢 Hot. Default: auto-generated 64-char hex. JWT signing key. Change this. If default/empty, a warning is logged at boot and TEMPORARY_INSECURE_KEY is used.

AUTH_TOKEN_EXPIRE_MINUTES

🟢 Hot. Default: 10080 (7 days). Session token lifetime in minutes.

Privacy & Location

SEND_LOCAL_NODE_LOCATION

🔴 Restart. Default: True. Share your local node's position on the map.

SEND_OTHER_NODES_LOCATION

🔴 Restart. Default: True. Forward positions of nodes your radio hears.

LOCATION_OFFSET_ENABLED

🔴 Restart. Default: False. Randomly offset coordinates for privacy.

LOCATION_OFFSET_METERS

🔴 Restart. Default: 0.0. Maximum random offset in metres (only used when LOCATION_OFFSET_ENABLED=True).

Storage & Engine

DB_PATH

🟢 Hot (path live), 🔴 Restart (takes effect). Default: meshtastic_data.db. SQLite database path. Docker installs use data/meshtastic_data.db.

TASK_DB_PATH

🔴 Restart. Default: tasks.db. SQLite path for task scheduler.

MAX_PACKETS_MEMORY

🟢 Hot. Default: 200. In-memory packet ring buffer size per slot. Higher = more data in RAM for the UI. Resizes deque immediately.

HISTORY_DAYS

🟢 Hot. Default: 1. Days of averaged metrics history to retain for charts. Separate from raw data retention.

DATA_RETENTION_DAYS

🔴 Restart. Default: 7. Days of packets/messages/positions/telemetry to retain. Prune runs periodically in background.

LOG_LEVEL

🟢 Hot. Default: INFO. One of: DEBUG, INFO, WARNING, ERROR. Changes root logger level immediately.

Connection Scheduler

SCHEDULER_MAX_RETRIES

🔴 Restart. Default: 3. Max consecutive reconnect attempts before giving up.

SCHEDULER_RETRY_DELAY_SECONDS

🔴 Restart. Default: 10. Base delay between reconnect attempts (seconds).

SCHEDULER_CONNECT_TIMEOUT

🔴 Restart. Default: 10.0. Timeout for initial connection (seconds).

SCHEDULER_RW_TIMEOUT

🔴 Restart. Default: 30.0. Timeout for read/write operations (seconds).

Remote C2 Access

REMOTE_C2

🔴 Restart. Default: False. Enable remote C2 access via meshdash.co.uk. Heartbeat always active regardless.

C2_ACCESS_LEVEL

🔴 Restart. Default: read. Permission tier. One of: heartbeat, monitor, read, operator, full.

COMMUNITY_API

🔴 Restart. Default: False. Appear on public community map (legacy — now part of Remote C2).

COMMUNITY_API_KEY

🔴 Restart. Default: YOUR_SUPER_SECRET_API_KEY_REPLACE_ME. API key for C2 server authentication. Treat like a password.

C2 Access Tiers

Tier	GET Access	POST Access
`heartbeat`	`/api/status`, `/api/stats`, version	(none)
`monitor`	heartbeat + nodes, channels, neighbors, local_node	(none)
`read`	monitor + packets, messages, metrics, traceroutes, waypoints, hardware_logs, connection_history	(none)
`operator`	read all	`/api/messages`, `/api/alert`, `/api/monitor`, `/extract`
`full`	read all	operator + `/api/console`, `/api/system/restart`, `/api/tasks/`, `/api/auto_reply/`

Community & Heartbeat

HEARTBEAT_INTERVAL_MINUTES

🔴 Restart. Default: 1. Interval between heartbeat pings to meshdash.co.uk. Always active — not user-configurable in UI.

COMMUNITY_API_HOST

🔴 Restart. Default: https://meshdash.co.uk. Override C2/heartbeat server URL.

Public Mode

PUBLIC_MODE

🟢 Hot. Default: True. When True, uses ephemeral in-memory databases and no authentication. When False, full auth with user accounts. Set to False for production.

INITIAL_ADMIN_USERNAME

Consumed on first boot, then removed from config. Default: None. Admin username to create.

INITIAL_ADMIN_PASSWORD

Consumed on first boot, then removed from config. Default: None. Admin password to create.

Optional Config Keys

CORS_ORIGINS

Default: (empty). Comma-separated CORS allowed origins. If set, overrides default ["*"]. http://localhost:{port} and http://127.0.0.1:{port} always appended.

Hot-Reload vs Restart — Complete Reference

Hot-Reloaded Keys (applied immediately)

#	Key	Effect
1	`AUTH_SECRET_KEY`	Updates JWT signing key
2	`AUTH_TOKEN_EXPIRE_MINUTES`	Updates session timeout
3	`WEBSERVER_PORT`	Updates port global
4	`DB_PATH`	Updates DB path global
5	`HISTORY_DAYS`	Updates chart retention window
6	`COMMUNITY_API_KEY`	Updates C2 API key
7	`PUBLIC_MODE`	Updates PUBLIC_MODE flag
8	`MAX_PACKETS_MEMORY`	Resizes in-memory packet deque
9	`LOG_LEVEL`	Changes root logger level

Restart-Required Keys

All other config keys require a server restart to take effect. This includes connection-type changes, serial port paths, BLE MAC addresses, scheduler parameters, privacy settings, C2 access level, and data retention. The Settings UI saves all changes to the config file and applies hot-reloads where possible, then displays: "Configuration saved. Some changes require a server restart."

Config File Format

# ---------------------------------------------------------
# MeshDash Configuration
# Updated via Web UI on 2026-05-17T19:49:24
# ---------------------------------------------------------

MESHTASTIC_HOST=10.0.0.50
MESHTASTIC_PORT=4403
MESHTASTIC_CONNECTION_TYPE=TCP
MESHTASTIC_SERIAL_PORT=
MESHTASTIC_BLE_MAC=
WEBSERVER_HOST=0.0.0.0
WEBSERVER_PORT=8181
AUTH_SECRET_KEY=your_secret_key_here
AUTH_TOKEN_EXPIRE_MINUTES=10080
SEND_LOCAL_NODE_LOCATION=True
SEND_OTHER_NODES_LOCATION=True
LOCATION_OFFSET_ENABLED=False
LOCATION_OFFSET_METERS=50.0
DB_PATH=data/meshtastic_data.db
TASK_DB_PATH=data/tasks.db
MAX_PACKETS_MEMORY=200
HISTORY_DAYS=1
DATA_RETENTION_DAYS=7
LOG_LEVEL=INFO
SCHEDULER_MAX_RETRIES=3
SCHEDULER_RETRY_DELAY_SECONDS=10
SCHEDULER_CONNECT_TIMEOUT=10.0
SCHEDULER_RW_TIMEOUT=30.0
REMOTE_C2=True
C2_ACCESS_LEVEL=full
COMMUNITY_API=True
COMMUNITY_API_KEY=your_api_key_here
HEARTBEAT_INTERVAL_MINUTES=1
PUBLIC_MODE=False

Parsing Rules

One KEY=VALUE per line
# starts a comment (whole line ignored)
Whitespace around = is stripped
Boolean values: True/False, true/false, 1/0, yes/no, on/off
Integer values: parsed as int(float(value))
Unknown keys are silently ignored
INITIAL_ADMIN_USERNAME and INITIAL_ADMIN_PASSWORD are consumed on first boot and removed

Multi-Slot Limits — Hardcoded Constants

These are not in the config file — they are compile-time constants in the source:

Constant	Default	Location	Description
`MAX_SLOTS`	`16`	`meshtastic_dashboard.py`	Maximum additional radio slots (beyond `node_0`)
`MAX_SSE_CLIENTS`	`50`	`meshtastic_dashboard.py`	Maximum concurrent SSE connections
`_PLUGIN_HANG_TIMEOUT`	`120` (2 min)	`meshtastic_dashboard.py`	Seconds before plugin with `watchdog:true` is flagged as hung
`_PLUGIN_LOG_MAX_LINES`	`250`	`meshtastic_dashboard.py`	Per-plugin in-memory log buffer (lines)
`WATCHDOG_AUTO_RECOVER`	`True`	`meshtastic_dashboard.py`	Auto-recover hung plugins (3x attempts, 5s apart)
`_MAX_LOGIN_ATTEMPTS`	`5`	`core/middleware.py`	Failed login attempts before account lockout
`_LOCKOUT_SECONDS`	`300` (5 min)	`core/middleware.py`	Duration of login lockout
Packet queue maxsize	`2000`	`meshtastic_dashboard.py`	Bounded asyncio.Queue per slot

MQTT Per-Slot Configuration

MQTT slots are configured via the Add Radio modal (not in .mesh-dash_config). They are persisted in data/slots.json.

MQTT Broker Settings

MQTT_BROKER

Default: mqtt.meshtastic.org. MQTT broker hostname.

MQTT_PORT

Default: 1883. Broker port (use 8883 for TLS).

MQTT_USERNAME

Default: meshdev. Broker username.

MQTT_PASSWORD

Default: large4cats. Broker password.

MQTT_TLS

Default: False. Enable TLS for broker connection.

MQTT_REGION

Default: EU_868. Required — public broker rejects wildcard subscriptions. Available codes: US_915, EU_868, EU_433, CN_470, JP_433, ANZ_919, KR_920, TW_920, RU_920, IN_866, NZ_915, TH_920, LORA_24, UA_868.

MQTT_CHANNEL

Default: # (all channels). Filter: LongFast, LongSlow, MedFast, etc.

MQTT_NODE_ID

Default: (empty). Your node's hex ID (e.g. !aabbccdd). If set, matching NodeInfo packets are promoted to local. If empty, slot runs in observer mode (receive-only).

MQTT_CLIENT_ID

Default: auto-generated. Auto-generated as meshdash_{slot_id}_{random} if empty.

MQTT_ROOT_TOPIC

Default: (empty). Override the full MQTT subscribe topic. Default path: msh/{REGION}/2/e/{CHANNEL}/#.

MQTT Packet Filters (Firehose)

MQTT_DROP_TELEMETRY

Default: False. Drop TELEMETRY_APP packets (battery, voltage, environment).

MQTT_DROP_NEIGHBOR

Default: False. Drop NeighborInfo packets (can be massive on busy networks).

MQTT_DROP_POSITION

Default: False. Drop POSITION_APP packets.

MQTT_DROP_NODEINFO

Default: False. Drop NODEINFO_APP packets.

MQTT_DROP_ENCRYPTED

Default: False. Drop encrypted packets that can't be decrypted with known keys.

MQTT_DROP_ROUTING

Default: False. Drop ROUTING_APP and TRACEROUTE_APP packets.

Filter Presets

Preset	Telemetry	Neighbor	Position	NodeInfo	Encrypted	Routing
Maximum (Text Only)	✓ drop	✓ drop	✓ drop	✓ drop	✓ drop	✓ drop
Standard (recommended)	✓ drop	✓ drop	✗ keep	✗ keep	✓ drop	✓ drop
Minimal (Heavy Data)	✗ keep	✓ drop	✗ keep	✗ keep	✓ drop	✗ keep
No Filters (Firehose)	✗ keep	✗ keep	✗ keep	✗ keep	✗ keep	✗ keep

MQTT Broker Presets

Preset	Broker	Port	Username	Password	TLS
Meshtastic Public	`mqtt.meshtastic.org`	`1883`	`meshdev`	`large4cats`	No
Meshtastic Public TLS	`mqtt.meshtastic.org`	`8883`	`meshdev`	`large4cats`	Yes

MQTT Manager Internal Constants

RECONNECT_DELAY_MIN

2.0 seconds — minimum reconnect backoff

RECONNECT_DELAY_MAX

60.0 seconds — maximum reconnect backoff

HEALTH_CHECK_INTERVAL

15.0 seconds between health checks

CONNECT_TIMEOUT

15.0 seconds

MAX_RECONNECT_ATTEMPTS

50 consecutive reconnect attempts

MeshCore Per-Slot Configuration

MeshCore slots are configured via the Add Radio modal and persisted in data/slots.json.

MESHCORE_TRANSPORT

Default: serial. One of: serial, tcp, ble.

MESHCORE_SERIAL_PORT

Default: /dev/ttyUSB0. Serial device path (transport=serial).

MESHCORE_BAUD

Default: 115200. Baud rate (transport=serial).

MESHCORE_HOST

Default: 192.168.1.100. IP/hostname (transport=tcp).

MESHCORE_PORT

Default: 4000. TCP port (transport=tcp).

MESHCORE_BLE_MAC

Default: (empty). Bluetooth MAC address (transport=ble).

MESHCORE_BLE_PIN

Default: (empty). BLE pairing PIN.

MESHCORE_LABEL

Default: (empty). Human-readable label for display.

MeshCore Manager Internal Constants

RECONNECT_DELAY_MIN

3.0 seconds — minimum reconnect backoff

RECONNECT_DELAY_MAX

60.0 seconds — maximum reconnect backoff

HEALTH_CHECK_INTERVAL

30.0 seconds between health checks

CONNECT_TIMEOUT

20.0 seconds

MAX_RECONNECT_ATTEMPTS

50 consecutive reconnect attempts

MSG_FETCH_INTERVAL

2.0 seconds — fallback get_msg() poll interval

_RX_LOG_WINDOW

0.6 seconds — RX_LOG correlation window matching meshcore-ha pattern

MeshCore transport notes:

Serial (recommended): Real USB serial adapters only (/dev/ttyUSB0, /dev/ttyACM0, COM3). Pseudo-ttys (socat) fail because MeshCore sets RTS/DTR signals.
TCP: Connects to a MeshCore TCP bridge service.
BLE (experimental): OS-dependent pairing — Linux requires prior bluetoothctl pairing; macOS uses system Bluetooth UI. PIN supported.

Hot-Reload vs Restart Decision Tree

Need to change a config value?
  │
  ├─ AUTH_SECRET_KEY / TOKEN_EXPIRE / WEBSERVER_PORT / DB_PATH / HISTORY_DAYS /
  │  COMMUNITY_API_KEY / PUBLIC_MODE / MAX_PACKETS_MEMORY / LOG_LEVEL
  │  └─ 🟢 HOT — change via Settings UI, applies immediately, no restart
  │
  └─ Everything else (connection type, serial port, BLE MAC, scheduler,
     privacy settings, C2 access level, data retention, etc.)
     └─ 🔴 RESTART — change via Settings UI, then click "RESTART SERVICE"

See also: Radio Connection for per-slot MQTT and MeshCore configuration.

C2 Terminal Connection Manager