Meshyface

Meshyface is a chat-first Meshtastic dashboard that runs as a single Python service and serves a single-page web UI over HTTP.

Current App Surface

The current UI exposes:

• Chat plus direct-peer conversations
• Network workspace for map, overview, links, routes, sensors, Top 10 rankings, node details, and on-demand history
• Console workspace for live packet/log output
• Apps workspace with Games and a Files tab when file transfer is enabled
• Settings workspace with radio, device, connectivity, location, channels, tickers, lists, appearance, and about panes
• SQLite-backed history, search, rollups, theme persistence, and custom telemetry rule persistence

Console workspace

The Console workspace is a terminal-style control surface for packet traffic, history search, and mesh utility commands.

• Type a command name to open autocomplete suggestions. Use Tab or Enter to accept, ArrowRight to accept the ghosted suffix, and ArrowUp / ArrowDown to move through the popup.
• Commands that take a node target show rich node suggestions with name, ID, emoji, tag, status, hops, GPS, last-heard state, ports, and node number. Normal text narrows by node names and tags; ! narrows by node ID.
• live streams packet traffic until Ctrl+C or q. Use live grep <text>, live rg <text>, live filter=<text>, or bare live <text> to stream only matching live packet groups. Layer and verbosity filters still apply, for example live rg TEXT_MESSAGE_APP -vv --layer=2.
• grep <text> and rg <text> search retained packet/chat history with context windows, limits, packet/chat source filters, and summary/packet scope filters.
• /search <text> filters the visible console output from the prompt without starting a retained-history search.

Screenshots

Live network map

Map view with node locations, links, common paths, clusters, and signal heatmap.

Network overview

History view for node counts, online status, new nodes, and position reports.

Link topology

Topology view showing observed links from the selected root node.

Route trace

Trace view for a source, destination, nearby links, and per-hop packet details.

Sensor history

Telemetry chart comparing sensor history across multiple nodes.

Status cards

Top cards for radio activity, node counts, packets, links, battery, and channel use.

Theme customization

Themes can reshape the full dashboard with custom colors, gradients, transparency, blur, fonts, particles, or a live-map background. These example palettes are custom themes; select any preview to open its full-resolution screenshot.

Signal Green	Neon Magenta	Aurora Relay

Shared node appearances

Meshyface nodes can share compact appearance packets containing a node-theme recipe and an optional ghost or watermark. Configure and preview your node in Settings > Appearance > Node Appearance, enable Share node appearance, then use Broadcast appearance to publish it.

• Appearance packets use the configured Profiles send channel and inherit the radio's hop-limit setting; Meshyface does not impose a separate hop limit.
• Received appearances can style node identities in chat, rosters, node details, maps, graphs, sensors, and tickers without replacing the receiving dashboard's own theme.
• Turning Share node appearance off disables both sides of the feature. It stops broadcasts and bypasses the profile receive path before incoming appearance payloads are decoded, cached, or persisted; cached shared appearances are cleared and no received appearance is rendered.
• When history is enabled, received profiles and the local sharing preference persist in the history SQLite database.
• Shared appearances are cosmetic metadata. A received appearance does not change radio settings, channels, or the dashboard's saved package theme.

System Architecture

flowchart LR
  Browser["Browser<br/>single-page UI"]
  CDN["Vendored browser assets<br/>Leaflet + leaflet.heat + particles.js"]
  Tiles["Basemap provider<br/>OpenStreetMap tile service"]
  Server["ThreadingHTTPServer<br/>HTML shell + JSON API"]
  Assets["Python template assembly<br/>meshdash/html* + meshdash/assets/*"]
  State["State loaders<br/>live snapshot + history readers"]
  Services["Write services<br/>chat, settings, tools, games, optional files"]
  Tracker["DashboardTracker<br/>live receive path + in-memory buffers"]
  History["HistoryStore / SQLite (WAL)<br/>chat, packets, rollups, settings"]
  Radio["Meshtastic interface<br/>serial or TCP"]
  Mesh["Meshtastic radio / mesh"]
  Atlas["Bundled offline atlas<br/>reference basemap fallback"]

  Browser -->|GET /| Server
  Browser -->|GET /api/*| Server
  Browser -->|POST write APIs| Server
  Browser --> CDN
  Browser --> Tiles
  Browser -->|fallback basemap data| Atlas
  Server --> Assets
  Server --> State
  Server --> Services
  State <--> Tracker
  State <--> History
  Services <--> History
  Services <--> Radio
  Radio <--> Mesh
  Radio -->|receive callbacks| Tracker

Installation

Start with prerequisites and dependencies, then choose one install path:

• Manual foreground run: clone anywhere and run the dashboard directly.
• Recommended systemd service: clone into /opt/meshyface for a persistent GitHub-updatable host.
• Docker: run the same app entrypoint in a container with /data mounted for persistent state.
• Workstation push deployment: copy a local checkout to a target over SSH.
• Proxmox runtime topology: choose TCP or USB radio placement for a VM/LXC install.
• Offline map packs: add detailed local map data for air-gapped or low-connectivity dashboards.

Data And Storage

Shared history database