config.example.json

{
  "port": 3000,
  "apiKey": "your-secret-api-key-here",
  "nodeBlacklist": [],
  "_comment_nodeBlacklist": "Public keys of nodes to hide from all API responses. Use for trolls, offensive names, or nodes reporting false data that operators refuse to fix.",
  "hiddenNamePrefixes": ["🚫"],
  "_comment_hiddenNamePrefixes": "Node name prefixes that mark a node as hidden from this dashboard (#1181). Mirrors a convention used by other MeshCore map dashboards: an operator who wants their node hidden renames it to start with one of these prefixes and sends an advert; the next advert is dropped from /api/nodes, /api/nodes/search and /api/nodes/{pubkey}. DB rows are preserved so observation history (paths, hops, distances) stays intact for analytics. The node is NOT hidden from the mesh itself — only from this dashboard. Set to [] to disable. Default: [\"🚫\"].",
  "observerIATAWhitelist": [],
  "_comment_observerIATAWhitelist": "Global IATA region whitelist. When non-empty, only observers whose IATA code (from MQTT topic) matches are processed. Case-insensitive. Empty = allow all. Unlike per-source iataFilter, this applies across all MQTT sources. A dropped region is logged by the ingestor as one '[region-filter] dropping region \"XYZ\"' line, repeated at most every iataWarnIntervalSec while it keeps arriving.",
  "iataWarnIntervalSec": 21600,
  "_comment_iataWarnIntervalSec": "Optional (ingestor). Seconds between repeated '[region-filter]' warnings for a region dropped by observerIATAWhitelist. Default 21600 (6h); 0 or omitted = default; maximum 86400 (24h), larger values are capped. At most 512 regions are tracked individually (region codes come from the MQTT topic, so this is bounded); beyond that, drops share one overflow warning with the same interval.",
  "retention": {
    "nodeDays": 7,
    "observerDays": 14,
    "packetDays": 30,
    "channelDays": 0,
    "clientRxDays": 30,
    "clientRegionsDays": 0,
    "inactiveNodeDays": 0,
    "nodeChangeDays": 0,
    "observerPurgeDays": 0,
    "_comment_tableRetention": "Opt-in (ingestor, #329) retention for the tables nothing else prunes; each is in days, 0 or omitted = keep forever (the default). Applied at ingestor startup and daily with the observer retention pass, in batches. inactiveNodeDays: inactive_nodes rows whose last advert is older than N days are deleted, unless the node has come back or is an observer still uploading; a deleted node that adverts again later counts as new (no 'resurrected' change, listed in New Nodes). Set it above nodeDays. nodeChangeDays: node_changes rows (Tools > Node Changes) detected more than N days ago are deleted. observerPurgeDays: observers already marked inactive by observerDays AND not seen in N days are hard-deleted with their observer_neighbors snapshot, but only when no observation, observer_metrics, observer_neighbor_metrics or dropped_packets row still references them. Set it above observerDays, packetDays (and channelDays) and metricsDays; below those an observer waits until that data has aged out. Example: an operator honouring a 30-day retention period sets all three to 30. ping_triggers (Ping Scores triggers, with sender names) has no window and is kept forever, because the all-time Ping Scores records need it.",
    "_comment": "nodeDays: nodes not seen in N days moved to inactive_nodes (default 7). observerDays: observers not sending data in N days are removed (-1 = keep forever, default 14). packetDays: transmissions older than N days are deleted (0 = disabled). channelDays: channel messages (GRP_TXT) and their observations are kept until they are N days old instead of packetDays; only takes effect when packetDays is set and channelDays is larger (0 = channel messages follow packetDays, default) (#296). The server's in-memory window (packetStore.retentionHours) is separate; channel history is read from the database. clientRxDays: mobile client-RX coverage rows (client_receptions/client_observers) older than N days are deleted (0 = disabled) — bounds the opt-in coverage tables (#1727). clientRegionsDays: declared-region reports (client_declared_regions, by reported_at) older than N days are deleted, and reports older than that are refused at ingest; 0 or omitted follows clientRxDays, and 30 days when that is 0 too — this table is never unbounded (#126, docs/client-regions.md). NOTE (#1283): all retention fields are consumed by the INGESTOR process. The server is read-only and never prunes."
  },
  "db": {
    "vacuumOnStartup": false,
    "incrementalVacuumPages": 1024,
    "load": {
      "chunkSize": 10000,
      "_comment": "chunkSize: rows fetched per chunk by PacketStore.LoadChunked during startup (#1009). Default 10000. Lower values surface the early-HTTP-readiness signal sooner (the listener binds after the first chunk) at the cost of more SQL round-trips. Higher values reduce per-chunk overhead but delay first-chunk readiness. The X-CoreScope-Load-Status response header reports loading|ready and progress=<rows> until the load completes."
    },
    "_comment": "vacuumOnStartup: run one-time full VACUUM to enable incremental auto-vacuum on existing DBs. Executed by the INGESTOR at startup, BEFORE the MQTT subscriber starts (#1283), so there is no contention with concurrent writes. Blocks ingestor startup for minutes on large DBs; requires 2x DB file size in free disk space. incrementalVacuumPages: free pages returned to OS after each retention reaper cycle (default 1024). See #919. load.chunkSize: see nested _comment (#1009).",
    "_comment_slowWriterMs": "#1340 — SQLite writer-lock log threshold (default 500). Any wrapped writer call (tagged neighbor_builder, mqtt_handler, prune_packets, prune_observers, prune_metrics, vacuum) whose hold_ms exceeds this emits a single [db-slow-writer] log line. Configured per-process via the CORESCOPE_DB_SLOW_WRITER_MS environment variable on the INGESTOR (e.g. CORESCOPE_DB_SLOW_WRITER_MS=200 for tighter alerting). Per-component wait_ms / hold_ms / contention_total histograms are surfaced via /api/perf/write-sources under .writer_perf regardless of this threshold."
  },
  "resolvedPathBackfill": {
    "disabled": false,
    "batchSize": 500,
    "pauseMs": 250,
    "_comment": "Optional (ingestor, #188). Once per ingestor start, re-resolves observations stored with resolved_path = NULL, from a persisted watermark up to the newest observation at the start of the pass. It waits until a neighbour-edge build has caught up with the stored observations and found at least one edge, then works in batches: each batch reads batchSize rows, resolves them outside any lock, and writes the results and the new watermark in one short write transaction, then sleeps pauseMs. Rows that still do not resolve stay NULL and are not retried. disabled: true skips the pass. batchSize: rows per batch, default 500. pauseMs: milliseconds between batches, default 250, which caps the pass at about 2,000 rows/s. For both numbers, 0 or omitted means the default, so the pause cannot be turned off; the smallest pause is 1. The server sees backfilled values only after its next restart."
  },
  "decodeBackfill": {
    "disabled": false,
    "batchSize": 300,
    "idWindow": 20000,
    "pauseMs": 250,
    "pollSeconds": 30,
    "_comment": "Optional (ingestor, #380). Re-decodes historical rows whenever the effective key set grows: a hashChannels/channelKeys addition plus a SIGHUP or restart, an approved shared channel, or an approved region scope. Stored enc_<HEX> GRP_TXT rows and transport-scoped rows whose region is unknown are re-decoded through the normal decode path, so a rewritten channel_hash, decoded_json or scope_name is byte-identical to the same packet ingested fresh. Already-resolved rows are never touched and an ambiguous region match abstains. One run at a time, resumed from a persisted watermark after a crash or a restart: each batch scans at most idWindow transmission ids and at most batchSize matching rows, writes them in one short transaction together with the new watermark, then sleeps pauseMs. disabled: true runs no pass; it only keeps forgetting keys that are revoked or removed, so turning the pass back on re-reads what arrived while they were gone. A key is its name and its value: a new value under a configured name starts a pass of its own. pollSeconds: how often the effective key set is checked for growth, default 30. For every number, 0 or omitted means the default, so the pause cannot be turned off. Progress is on /api/healthz under decode_backfill and in /api/perf/write-sources as backfill_decode_channel / backfill_decode_scope. Measure first: scripts/decode-backfill-estimate.sh prints the candidate counts and the estimated cost of one pass, read-only. A running server picks the rewrites up on its next poll for the SQL-backed channel and scope surfaces; its in-memory copies of rows loaded earlier refresh at its next start."
  },
  "listLimits": {
    "packetsMax": 10000,
    "nodesMax": 2000,
    "analyticsMax": 200,
    "channelMessagesMax": 500,
    "bulkHealthMax": 200,
    "_comment": "Maximum row counts returned by list API endpoints. These enforce a DoS-bounded ceiling for both UI and external requests. Operators with small/embedded deployments can tighten these; operators running large regional meshes can raise them. bulkHealthMax is intentionally separate from nodesMax: /api/nodes/bulk-health is per-row much heavier than /api/nodes (it joins per-node observer health + recent-packet stats) so its ceiling stays low (default 200) even if nodesMax is raised."
  },
  "_comment_ingestorStats": "Ingestor publishes a 1-Hz stats snapshot consumed by the server's /api/perf/io and /api/perf/write-sources endpoints (#1120). Path is configured via the CORESCOPE_INGESTOR_STATS environment variable on the INGESTOR process. Default: /tmp/corescope-ingestor-stats.json. The writer uses O_NOFOLLOW + 0o600, so a pre-planted symlink in /tmp cannot be used to clobber an arbitrary file. SECURITY: in shared-tmp environments (multi-tenant hosts), point CORESCOPE_INGESTOR_STATS at a private directory like /var/lib/corescope/ingestor-stats.json that only the corescope user can write to.",
  "corsAllowedOrigins": [],
  "_comment_corsAllowedOrigins": "Cross-origin allowlist for embed scenarios (#1369) AND for /ws WebSocket upgrades (#1793 — CSWSH defense per OWASP WebSocket Security Cheat Sheet). Exact-match origins, e.g. [\"https://blog.example.com\", \"https://embed.example.com\"]. Same-origin requests (Origin host == request Host) and non-browser clients (no Origin header) are always allowed for /ws. When empty (default), no Access-Control-* headers are sent and browsers enforce same-origin; cross-origin /ws upgrades are rejected. When non-empty, only the listed origins receive CORS headers, and Access-Control-Allow-Methods is limited to GET, HEAD, OPTIONS (the cross-domain surface is read-only — same-origin admin writes are unaffected). Use [\"*\"] to allow any origin for CORS XHR (NOT recommended for write-capable deployments); note that \"*\" is deliberately NOT honored for /ws upgrades — list explicit origins to permit cross-origin WebSocket clients (OWASP guidance: avoid wildcards in CSWSH defense). Operators can override per-deployment with the CORS_ALLOWED_ORIGINS environment variable (comma-separated). No credentialed CORS is enabled. To embed the map or channels pages cross-domain, add the embedding origin here and use the URL pattern '/#/map?embed=1' or '/#/channels?embed=1' — embed mode hides the top-nav, bottom-nav, and side drawer for full-bleed iframe rendering.",
  "webSocket": {
    "maxClients": 512,
    "_comment_maxClients": "#369 - GLOBAL ceiling on concurrent /ws clients, across every address. On by default at 512, because unlike the per-IP limits below it still works behind a reverse proxy: it counts connections, not clients. Sizing: the web UI opens exactly one socket per browser tab, and each accepted client costs roughly 12 KB of server heap, two goroutines, one file descriptor and a 256-message send queue (the queue is the part worth bounding — a stalled client can hold a quarter of a megabyte of pending broadcasts). 512 therefore sits far above any realistic tab count for a regional mesh while capping the worst case at a few hundred MB and keeping descriptors to half of the common 1024 soft limit. Excess clients get 503 with Retry-After before the handshake, and the refusals are counted in /api/stats under websocket.rejectedGlobalCap - watch that together with websocket.clients and raise this if real visitors are being turned away. Set 0 to remove the ceiling entirely (not recommended on a public instance).",
    "maxConnsPerIP": 0,
    "_comment_maxConnsPerIP": "#1794 - concurrent /ws connections allowed from one client address. 0 = off, and that is the shipped default ON PURPOSE: carrier-grade NAT puts thousands of unrelated mobile subscribers behind one public IPv4, so a low cap refuses real visitors while a scraper simply rents more addresses. Set it only if you know your audience is not behind shared NAT.",
    "upgradesPerMinPerIP": 30,
    "_comment_upgradesPerMinPerIP": "#1794 - handshakes per minute from one client address. On by default. Safe under CGNAT: a real client upgrades a handful of times per minute even while reconnecting, so 30 leaves ordinary traffic alone while flattening a scraper reconnect loop. Set 0 to disable.",
    "trustedProxies": [],
    "_comment_trustedProxies": "#1794 - addresses or CIDRs of YOUR reverse proxy. REQUIRED for the per-IP limits to do anything behind nginx/Caddy/Traefik/ingress: without it every visitor shares the proxy's address, so the limits are skipped and one warning is logged at startup. X-Forwarded-For is believed only from these addresses, because anyone else can forge it. Never list an address you do not control.",
    "deny": [],
    "_comment_deny": "#1794 - addresses or CIDRs refused at the /ws upgrade, before the handshake. Accepts both \"1.2.3.4\" and \"1.2.3.0/24\". Applies even behind an unconfigured proxy, since it is your explicit instruction. Rejections are counted in /api/stats under websocket.rejectedDeny."
  },
  "https": {
    "cert": "/path/to/cert.pem",
    "key": "/path/to/key.pem",
    "_comment": "TLS cert/key paths for direct HTTPS. Most deployments use Caddy (included in Docker) for auto-TLS instead."
  },
  "branding": {
    "siteName": "CoreScope",
    "tagline": "Real-time MeshCore LoRa mesh network analyzer",
    "logoUrl": null,
    "faviconUrl": null,
    "homeUrl": null,
    "_comment": "Customize site name, tagline, logo, and favicon. logoUrl/faviconUrl can be absolute URLs or relative paths. homeUrl (#1518) overrides the navbar logo link target — set to an absolute http(s):// URL for operators embedding CoreScope inside a larger site, or a '#'-prefixed app route (e.g. '#/home') to keep it in-app. Validator rejects javascript:, data:, vbscript:, file:, about:, protocol-relative '//', and bare paths to block XSS. Cross-origin URLs open in the SAME tab (no target=_blank); wrap with your own anchor if you need new-tab behavior. The mobile bottom-nav 🏠 button is intentionally NOT overridden — it stays in-app to preserve SPA back-stack on phones."
  },
  "theme": {
    "accent": "#4a9eff",
    "accentHover": "#6db3ff",
    "navBg": "#0f0f23",
    "navBg2": "#1a1a2e",
    "navActiveBg": "rgba(74,158,255,0.15)",
    "statusGreen": "#45644c",
    "statusYellow": "#b08b2d",
    "statusRed": "#b54a4a",
    "_comment": "CSS color overrides. Use the in-app Theme Customizer for live preview, then export values here. navActiveBg (#1509) controls the background of the currently-active top-nav link (the 'pill'); accepts any CSS color, typically a translucent rgba() so the nav gradient shows through."
  },
  "nodeColors": {
    "repeater": "#dc2626",
    "companion": "#2563eb",
    "room": "#16a34a",
    "sensor": "#d97706",
    "observer": "#8b5cf6",
    "_comment": "Marker/badge colors per node role. Used on map, nodes list, and live feed."
  },
  "markerStroke": {
    "color": "#fff",
    "width": 2,
    "opacity": 1,
    "_comment": "#1488/#1506 — outline around each map marker (live + map pages). Defaults restored to v3.7.2 visual (solid white, 2px). 'color' accepts any CSS color (hex, rgb, rgba); use rgba() or drop 'opacity' below ~0.5 to soften the outline when hundreds of nodes feel overwhelming. 'width' is the SVG stroke width (0 hides the outline entirely). Operators can override per-browser via the in-app Theme Customizer (Colors tab → Marker Stroke)."
  },
  "map": {
    "tiles": {
      "_comment_defaults": "#332 — the built-in defaults are 'osm-dark' / 'osm-standard' (keyless OpenStreetMap, tiles to zoom 18). Set darkDefault/lightDefault to any enabled style id to override; they take priority over the built-in fallback. Carto is NOT the default any more: since August 2026 keyless Carto raster tiles come back HTTP 200 with 'API KEY REQUIRED' stamped into the PNG, and CoreScope has no Carto basemap-key plumbing.",
      "_comment_legacy": "Legacy raw tile-URL overrides — \"tiles.dark\" / \"tiles.light\" at the top level, or \"darkUrl\" / \"lightUrl\" here — are still honoured: they apply when no provider was chosen in the browser and no darkDefault/lightDefault is set, i.e. precedence is browser choice > darkDefault/lightDefault > raw URL > built-in fallback. A raw URL carries no vendor metadata, so such a map shows the generic \"\u00a9 OpenStreetMap contributors\" credit (no vendor-specific or licence attribution), is never CSS-inverted in dark mode, and is capped at zoom 18 like the built-in OpenStreetMap default. Prefer darkDefault/lightDefault with a registered style id when you need the correct credit, licence link or a different zoom ceiling.",
      "darkDefault": "osm-dark",
      "lightDefault": "osm-standard",
      "providers": {
        "_comment_carto": "Carto styles stay available and selectable, but keyless raster tiles are watermarked 'API KEY REQUIRED' (see _comment_defaults). Optional: specify 'domain' for Carto enterprise (e.g. 'mycompany' for 'https://{s}.mycompany.cartocdn.com').",
        "carto": {
          "enabled": true,
          "domain": ""
        },
        "_comment_osm": "OSM providers: 'mapbox', 'thunderforest', 'maptiler'. WARNING: Tokens are sent to the browser. Apply origin/referrer restrictions in your provider dashboard.",
        "osm": {
          "enabled": false,
          "provider": "",
          "token": ""
        },
        "_comment_opentopomap": "OpenTopoMap topographical tile provider. Enabling this makes USERS' BROWSERS fetch tiles from tile.opentopomap.org, exposing their IP and approximate viewing area to that third party. Tiles are CC-BY-SA: the credit and licence link must stay on the map. Limited to zoom level 17, and it is a small volunteer-run service with informal fair-use expectations.",
        "opentopomap": {
          "enabled": false
        },
        "_comment_stamen": "Stamen (hosted by Stadia). WARNING: Tokens are sent to the browser. Apply origin/referrer restrictions.",
        "stamen": {
          "enabled": false,
          "token": ""
        },
        "_comment_usgs": "USGS topographical tile providers (USGS Topo, USGS Imagery). Enabling these makes USERS' BROWSERS fetch tiles from basemap.nationalmap.gov, exposing their IP and approximate viewing area to that third party. Limited to zoom level 16, and The National Map only serves the United States and its territories — elsewhere these layers render blank with no on-screen explanation.",
        "usgs": {
          "enabled": false
        }
      }
    }
  },
  "home": {
    "heroTitle": "CoreScope",
    "heroSubtitle": "Find your nodes to start monitoring them.",
    "steps": [
      {
        "emoji": "\ud83d\udce1",
        "title": "Connect",
        "description": "Link your node to the mesh"
      },
      {
        "emoji": "\ud83d\udd0d",
        "title": "Monitor",
        "description": "Watch packets flow in real-time"
      },
      {
        "emoji": "\ud83d\udcca",
        "title": "Analyze",
        "description": "Understand your network's health"
      }
    ],
    "checklist": [
      {
        "question": "How do I add my node?",
        "answer": "Search for your node name or paste your public key."
      },
      {
        "question": "What regions are covered?",
        "answer": "Check the map page to see active observers and nodes."
      }
    ],
    "footerLinks": [
      {
        "label": "\ud83d\udce6 Packets",
        "url": "#/packets"
      },
      {
        "label": "\ud83d\uddfa\ufe0f Network Map",
        "url": "#/map"
      },
      {
        "label": "\ud83d\udd34 Live",
        "url": "#/live"
      },
      {
        "label": "\ud83d\udce1 All Nodes",
        "url": "#/nodes"
      },
      {
        "label": "\ud83d\udcac Channels",
        "url": "#/channels"
      }
    ],
    "_comment": "Customize the landing page hero, onboarding steps, FAQ, and footer links."
  },
  "mqtt": {
    "broker": "mqtt://localhost:1883",
    "topic": "meshcore/+/+/packets",
    "_comment": "Legacy single-broker config. Prefer mqttSources[] for multiple brokers."
  },
  "mqttSources": [
    {
      "name": "local",
      "broker": "mqtt://localhost:1883",
      "topics": [
        "meshcore/+/+/packets",
        "meshcore/#"
      ]
    },
    {
      "name": "lincomatic",
      "broker": "mqtts://mqtt.lincomatic.com:8883",
      "username": "your-username",
      "password": "your-password",
      "rejectUnauthorized": false,
      "topics": [
        "meshcore/SJC/#",
        "meshcore/SFO/#",
        "meshcore/OAK/#",
        "meshcore/MRY/#"
      ],
      "iataFilter": [
        "SJC",
        "SFO",
        "OAK",
        "MRY"
      ],
      "region": "SJC",
      "connectTimeoutSec": 45
    },
    {
      "_comment": "WebSocket MQTT broker (e.g. meshcore-mqtt-broker). Use ws:// for plain WebSocket or wss:// for TLS. Username/password supported.",
      "name": "wsmqtt",
      "broker": "wss://wsmqtt.example.com/mqtt",
      "username": "corescope",
      "password": "your-password",
      "topics": [
        "meshcore/#"
      ]
    }
  ],
  "channelKeys": {
    "Public": "8b3387e9c5cdea6ac9e5edbaa115cd72"
  },
  "hashChannels": [
    "#LongFast",
    "#test",
    "#sf",
    "#wardrive",
    "#yo",
    "#bot",
    "#queer",
    "#bookclub",
    "#shtf"
  ],
  "channelProposals": {
    "enabled": false,
    "autoApprove": false,
    "maxPending": 100,
    "maxApproved": 128,
    "maxQueuedRequests": 256,
    "retentionDays": 30,
    "submissionsPerHour": 20
  },
  "_comment_channelProposals": "Shared hashtag channels: visitors suggest public hashtag channels (names only, never keys) on the Channels page. Submissions open only when enabled is true AND apiKey is strong (16+ characters, not a placeholder). By default an administrator approves or rejects suggestions at #/channels?view=proposals with the apiKey. Opt-in autoApprove immediately approves only brand-new names; existing pending, rejected and revoked names are not auto-approved. Approved channels are decrypted by the ingestor and listed for everyone, even before they carry traffic; they stay active if enabled is later set to false. Limits: maxPending/maxApproved bound the table, maxQueuedRequests bounds the request queue next to the database, submissionsPerHour is a global sliding window, and rejected or unreviewed suggestions are deleted after retentionDays. Read by both server and ingestor; changing this policy requires an ingestor restart.",
  "healthThresholds": {
    "infraDegradedHours": 24,
    "infraSilentHours": 72,
    "nodeDegradedHours": 1,
    "nodeSilentHours": 24,
    "relayActiveHours": 24,
    "observerOnlineMinutes": 60,
    "observerStaleMinutes": 1440,
    "_comment": "How long (hours) before nodes show as degraded/silent. 'infra' = repeaters & rooms, 'node' = companions & others. relayActiveHours: a repeater is shown as 'actively relaying' if its pubkey appeared as a path hop in a non-advert packet within this window (issue #662).",
    "_comment_observerThresholds": "Observer health classification. Online: last_seen < observerOnlineMinutes ago. Stale: between Online and observerStaleMinutes. Offline: beyond observerStaleMinutes. Defaults 60 / 1440 (1h / 24h) match the node thresholds for consistency and eliminate flap on low-traffic / CDN-fronted instances (#1552). Operators who want the old aggressive 10-min Online threshold can set observerOnlineMinutes: 10."
  },
  "defaultRegion": "SJC",
  "mapDefaults": {
    "center": [
      37.45,
      -122.0
    ],
    "zoom": 9
  },
  "geo_filter": {
    "polygon": [
      [37.80, -122.52],
      [37.80, -121.80],
      [37.20, -121.80],
      [37.20, -122.52]
    ],
    "bufferKm": 20,
    "_comment": "Optional. By default, also restricts GET /api/nodes (and therefore the live map) to nodes within the polygon + bufferKm — foreign_advert-tagged nodes are always kept regardless (#730, see foreignAdverts below); see geoFilterExemptNodeList to opt out of that. The prune-geo-filter admin flow always uses this polygon regardless of geoFilterExemptNodeList. Polygon is an array of [lat, lon] pairs (minimum 3). Use the GeoFilter tab in the Customizer (requires apiKey) or the GeoFilter Builder (`/geofilter-builder.html`) to draw a polygon visually and export a config snippet. Remove this section to disable filtering entirely. Nodes with no GPS fix are always allowed through."
  },
  "foreignAdverts": {
    "mode": "flag",
    "_comment": "Controls how the ingestor handles ADVERTs whose GPS is OUTSIDE the geo_filter polygon (#730). 'flag' (default): store the advert/node and tag it foreign_advert=1 so operators can see bridged/leaked nodes via the API ('foreign': true on /api/nodes). 'drop': legacy behavior — silently discard the advert (no log, no node row). Only applies when geo_filter is configured; otherwise has no effect."
  },
  "geoFilterExemptNodeList": false,
  "_comment_geoFilterExemptNodeList": "Optional, default false. When geo_filter is configured, GET /api/nodes (and therefore the live map) excludes out-of-polygon nodes by default — the long-standing #730 declutter behavior, preserved automatically for every deployment upgrading from before this field existed. Set to true if you want geo_filter purely for foreign_advert classification/analytics (e.g. a 'Foreign Traffic' investigation) WITHOUT also hiding out-of-polygon nodes from the node list/map. Per-request ?geoFilter=0 / ?geoFilter=1 on /api/nodes overrides either default for a single call. Has no effect on ingestion (foreignAdverts.mode) or the prune-geo-filter admin flow, both of which are unaffected by this flag.",
  "areas": {
    "_comment": "Optional. GPS-based display filter. Each entry defines a geographic area by polygon ([lat, lon] pairs) or bounding box (latMin/latMax/lonMin/lonMax). Packets and nodes are attributed to an area based on the transmitting node's own GPS coordinates — not the observer's location. Areas appear as a filter pill bar in the dashboard. Remove this section to disable the area filter UI.",
    "BAY": {
      "label": "Bay Area",
      "polygon": [
        [37.90, -122.55],
        [37.90, -121.75],
        [37.25, -121.75],
        [37.25, -122.55]
      ]
    },
    "SJC": {
      "label": "San Jose",
      "latMin": 37.20,
      "latMax": 37.45,
      "lonMin": -122.05,
      "lonMax": -121.75
    }
  },
  "regions": {
    "SJC": "San Jose, US",
    "SFO": "San Francisco, US",
    "OAK": "Oakland, US",
    "MRY": "Monterey, US"
  },
  "cacheTTL": {
    "stats": 10,
    "nodeDetail": 300,
    "nodeHealth": 300,
    "nodeList": 90,
    "bulkHealth": 600,
    "networkStatus": 600,
    "observers": 300,
    "channels": 15,
    "channelMessages": 10,
    "analyticsRF": 1800,
    "_comment_analyticsRF": "TTL (seconds) for the shared analytics result cache. Backs /api/analytics/rf, /api/analytics/topology, /api/analytics/distance, /api/analytics/hash-sizes, /api/analytics/channels, /api/analytics/subpaths. Default 60s if unset (#1239) — distance analytics is viewed live during active analysis, so the default smooths cold-miss churn without freezing data. Lower with care; sub-15s values can cause repeated multi-second cold computes during heavy ingest.",
    "analyticsTopology": 1800,
    "analyticsChannels": 1800,
    "analyticsHashSizes": 3600,
    "analyticsSubpaths": 3600,
    "analyticsSubpathDetail": 3600,
    "nodeAnalytics": 60,
    "nodeSearch": 10,
    "invalidationDebounce": 30,
    "_comment": "All values in seconds. Server uses these directly. Client fetches via /api/config/cache."
  },
  "liveMap": {
    "propagationBufferMs": 5000,
    "_comment": "How long (ms) to buffer incoming observations of the same packet before animating. Mesh packets propagate through multiple paths and arrive at different observers over several seconds. This window collects all observations of a single transmission so the live map can animate them simultaneously as one realistic propagation event. Set higher for wide meshes with many observers, lower for snappier animations. 5000ms captures ~95% of observations for a typical mesh.",
    "maxNodes": 2000,
    "_comment_maxNodes": "Maximum nodes the /live map fetches (and renders) in one page. Default 2000. Raise this on deployments that have measured perf headroom on mid-range mobile (heap + frame-time). Server clamps to [100, 20000]: misconfigured values are coerced silently. Also caps the matching /api/packets?limit fetch the live VCR-rewind code uses. Reporter: #1574."
  },
  "timestamps": {
    "defaultMode": "ago",
    "timezone": "local",
    "formatPreset": "iso",
    "customFormat": "",
    "allowCustomFormat": false,
    "_comment": "defaultMode: ago|local|iso. timezone: local|utc. formatPreset: iso|us|eu. customFormat: strftime-style (requires allowCustomFormat: true)."
  },
  "packetStore": {
    "maxMemoryMB": 1024,
    "estimatedPacketBytes": 450,
    "retentionHours": 168,
    "hotStartupHours": 0,
    "_comment": "In-memory packet store. maxMemoryMB caps RAM usage. retentionHours: only packets younger than this are kept in memory (0 = unlimited). hotStartupHours: hours loaded synchronously at startup; background loader fills the remaining retentionHours window. 0 = disabled (loads full retentionHours synchronously, legacy behavior). Set to a positive value (e.g. 24) to reduce startup time on large DBs.",
    "_comment_gomemlimit": "On startup the server reads GOMEMLIMIT from the environment if set; otherwise it derives a Go runtime soft memory limit of maxMemoryMB * 1.5 and applies it via debug.SetMemoryLimit. This forces aggressive GC under cgroup pressure so the process self-throttles before the kernel SIGKILLs it. To override, set GOMEMLIMIT explicitly (e.g. GOMEMLIMIT=850MiB). See issue #836."
  },
  "runtime": {
    "maxMemoryMB": 0,
    "_comment_runtime_maxMemoryMB": "Go soft memory limit (GOMEMLIMIT) in MiB applied via runtime/debug.SetMemoryLimit at startup. Precedence: GOMEMLIMIT env var > runtime.maxMemoryMB > packetStore.maxMemoryMB-derived (server only). 0 (default) preserves existing behavior. Set on memory-constrained deployments (2 GB Pi, 4 GB VMs) to trigger earlier GC and avoid container OOM-kill. Floor recommendation: ≥1.5× working set; setting below the working set causes a GC death-spiral. Applies to BOTH cmd/server and cmd/ingestor. See #1010."
  },
  "resolvedPath": {
    "backfillHours": 24,
    "_comment": "How far back (hours) the async backfill scans for observations with NULL resolved_path. Default: 24. Set higher to backfill older data, lower to speed up startup."
  },
  "ingestBufferSize": 50000,
  "_comment_ingestBufferSize": "Number of MQTT messages held in memory while the single SQLite writer is blocked by a startup migration/prune (#1608). Drained once the write path is ready; bounded memory (small closure per item). 0 / omit / negative => default 50000 (applied by IngestBufferSizeOrDefault before NewIngestBuffer). A positive value below the default is honored as-is; sub-1 values reaching NewIngestBuffer directly clamp to 1 with a WARN log.",
  "neighborGraph": {
    "maxAgeDays": 5,
    "maxEdgeKm": 500,
    "cacheRecomputeIntervalSeconds": 300,
    "_comment": "maxAgeDays: neighbor edges older than this many days are pruned on startup and daily. Default 5. maxEdgeKm: geo-implausibility filter — when both endpoints have GPS, edges with haversine distance > maxEdgeKm are rejected at build time to prevent disambiguator self-reinforcement on wide-geo MQTT deployments. Default 500 km (well above any plausible terrestrial LoRa hop). 0 ⇒ use default; set negative to disable the filter. Rejected count surfaces in /api/analytics/neighbor-graph stats. Issue #1228. cacheRecomputeIntervalSeconds: how often the background recomputer rebuilds the default-shape /api/analytics/neighbor-graph response (#1481 P0-1). Default 300 (5 min). Lower = fresher data, more CPU per minute. Issue #1483."
  },
  "estimatedPositions": {
    "enabled": true,
    "_comment": "Operator policy for neighbor-derived position estimates. Omit this section or enabled to preserve the default (true). Set false to disable estimates in node details, packet/Ping Scores paths, maps, and estimate-dependent analytics. Reported GPS, ordinary neighbor graphs, and independent IATA/name-based fallbacks are unchanged. Requires a Go server restart and browser refresh; not reloaded by SIGHUP."
  },
  "observersCache": {
    "ttlSeconds": 30,
    "_comment": "TTL for the default-shape /api/observers response cache (#1481 P0-3). Default 30s. Lower = fresher data, more SQL pressure on the 1.9M-row observations table. TTL-boundary refills are collapsed via singleflight so concurrent requests cause exactly one SQL fill. Issue #1483."
  },
  "knownChannelsUrl": "",
  "knownChannelsRefreshMs": 86400000,
  "_comment_knownChannels": "Issue #1323. OPT-IN community-maintained hashtag-channels catalogue. Empty string (default) = DISABLED: no background HTTP fetch is started and GET /api/known-channels returns an empty snapshot. To enable, set knownChannelsUrl to a pinned-SHA URL such as \"https://raw.githubusercontent.com/marcelverdult/meshcore-channels/072bc25b6fc983aa2aa7e9d399a97a5f4899ea71/channels-by-country.json\". The URL should point at the channels-by-country.json shape: {generated_at, license, countries:{cc:[{channel,description,key?}]}}. Always pin to a specific commit SHA (not the moving 'main' branch) so a hostile or compromised future upstream commit cannot be silently fetched by your deployment; periodically bump the pin after reviewing upstream diffs. Fetched in the background every knownChannelsRefreshMs (default 86400000 = 24h). Stored in-memory only — no DB, no disk cache. Surfaced over GET /api/known-channels?region=XX. Cache is fail-soft: a failed refresh keeps the last-known snapshot in place. No credentials are sent.",
  "batteryThresholds": {
    "lowMv": 3300,
    "criticalMv": 3000,
    "_comment": "Voltage cutoffs (millivolts) for the per-node battery trend chart on /node-analytics. Latest sample below lowMv shows the node as ⚠️ Low; below criticalMv shows 🪫 Critical. Both default to 3300 / 3000 if omitted. Source data: observer_metrics.battery_mv populated from observer status messages; only nodes that are themselves observers (matching pubkey ↔ observer id) yield a series. Issue #663."
  },
  "dutyCycleWarnPct": 10,
  "_comment_dutyCycleWarnPct": "TX airtime share (percent) over the last hour at which RF Health and the observer list flag an observer. Default 10, the EU 868 MHz g3 sub-band limit; raise it (e.g. 50) elsewhere. Repeater firmware defaults to a 50% budget (airtime_factor 1.0), so the device does not enforce this itself. Issue #479.",
  "_comment_mqttSources": "Each source connects to an MQTT broker. Supported schemes: mqtt:// (plain TCP), mqtts:// (TLS), ws:// (WebSocket), wss:// (WebSocket TLS). topics: what to subscribe to. iataFilter: only ingest packets from these regions (optional). region: default IATA region for this source — used when packet/topic doesn't specify one (optional, priority: payload > topic > this field). clientId: MQTT client ID, used verbatim (optional; must be unique among the broker's concurrent clients, and at most 23 characters of [0-9A-Za-z] for strict MQTT 3.1 brokers). When omitted, each ingestor start generates corescope-<name>-<8 random hex>, so copies of this file never share an ID — do not add a fixed clientId here.",
  "compression": {
    "gzip": false,
    "websocket": false,
    "level": 6,
    "minSizeBytes": 1024,
    "contentTypes": [
      "application/json",
      "application/javascript",
      "application/xml",
      "text/html",
      "text/css",
      "text/plain",
      "image/svg+xml"
    ]
  },
  "_comment_compression": "Opt-in HTTP gzip middleware + WebSocket permessage-deflate. Both default to false — enable ONLY when your upstream reverse proxy is NOT already compressing. gzip: enables the gzipMiddleware wrapper around the HTTP handler. websocket: sets gorilla websocket Upgrader.EnableCompression. level: gzip compression level 1..9 (1=BestSpeed, 9=BestCompression, default 6). minSizeBytes: advisory minimum response size below which compression would not pay off. contentTypes: MIME allow-list — only responses with these Content-Type values are compressed. Already-compressed types (image/*, video/*, audio/*, application/zip, application/x-gzip, application/pdf, application/octet-stream) are always skipped, as are responses whose handler already set Content-Encoding. Omit contentTypes to use the built-in default allow-list.",
  "clientRegions": { "enabled": false },
  "_comment_clientRegions": "Opt-in declared-region reports (#126): a mobile companion asks a repeater in direct range which regions it lets flood and relays the answer on meshcore/client/<pubkey>/regions; each answer is kept as a report in client_declared_regions with its collector, reported time, ingest time and the repeater's own clock. Default OFF and independent of clientRxCoverage. SINGLE FLAG, BOTH PROCESSES: it gates the ingest write path and GET /api/nodes/{pubkey}/declared-regions (404 when off), which serves reports without collector keys or positions. The clientRxCoverage.sources allowlist and observerBlacklist apply to this topic too. TRUST: requires a broker ACL binding meshcore/client/{pubkey}/regions to that publisher; target and regions are the collector's claim, never authoritative. Retention: retention.clientRegionsDays. Erasure: admin delete-client-rx also deletes the reports a key collected. See docs/client-regions.md.",
  "clientRxCoverage": { "enabled": false },
  "_comment_clientRxCoverage": "Opt-in mobile client-RX coverage (corescope-rx companions publishing GPS-tagged receptions to meshcore/client/<pubkey>/packets). Default OFF: when disabled the ingestor writes no client_receptions, the /api/rx-coverage|rx-leaderboard|nodes/{pubkey}/rx-coverage endpoints 404, and the UI hides the Coverage dashboard + Reach overlay. Set enabled=true to turn it on. SINGLE FLAG, BOTH PROCESSES: the ingestor and server each parse this same config.json, so this one clientRxCoverage.enabled entry gates both the ingest write path and the read endpoints — set it once, not per-process. TRUST: the feature requires an ACL-capable broker binding meshcore/client/{pubkey}/packets to that publisher; without ACLs the companion GPS is spoofable (see docs/client-rx-coverage.md). Retention: see retention.clientRxDays. Companion app + setup: https://github.com/efiten/corescope-rx.",
  "_comment_clientRxCoverage_sources": "OPTIONAL allow-list of mqttSources[].name entries that may contribute client RX coverage. Omitted or empty (the default) = every source is accepted, unchanged behaviour. Set it when this instance reads MORE THAN ONE broker and they do not all bind meshcore/client/<pubkey>/packets to the publisher holding that key: coverage is only as trustworthy as the weakest broker, so on a mixed deployment (one broker with per-device identity + one legacy username/password broker where many accounts may write meshcore/#) any account on the weak broker could otherwise inject coverage under any companion pubkey with any GPS position. Listing the trusted source names keeps the client namespace on those sources — a client message from any other source is dropped before any write (no client_receptions, no client_observers, no observer row), logged per source with throttling and a line cap. Matching is on the source name, trimmed and case-insensitive; a source with no name can never be listed. A name matching no configured source is logged once at startup. Example: \"clientRxCoverage\": { \"enabled\": true, \"sources\": [\"device-auth\"] }. See docs/client-rx-coverage.md.",
  "_comment_channelKeys": "Hex keys for decrypting channel messages. Key name = channel display name. public channel key is well-known.",
  "_comment_hashChannels": "Channel names whose keys are derived via SHA256. Key = SHA256(name)[:16]. Listed here so the ingestor can auto-derive keys.",
  "hashRegions": [
    "#belgium",
    "#eu"
  ],
  "_comment_hashRegions": "Region names for scope matching on transport-route packets. Key = SHA256('#name')[:16]. Add any region names used by nodes in your network.",
  "_comment_hashRegionsPath": "OPTIONAL path to an external JSON file holding region names as a plain array, e.g. [\"dk\", \"dk-aarhus\"] (issue #360). Omitted or empty (the default) = inline hashRegions only, exactly as before; there is no auto-discovered default file. When set, the effective set is the UNION of the inline hashRegions list above and the file, normalized the same way ('#' prefix added, whitespace trimmed, blank entries dropped) and deduplicated after normalization. Set it when the region list is large and machine-maintained: a real deployment carries ~1100 names, which is a third of config.json once hashChannels and areas are counted, and moving it out makes the rest reviewable. SINGLE KEY, BOTH PROCESSES: the ingestor (which derives one HMAC key per region) and the server (which reports unknown scopes in Observer Neighbors and unusedRegions in /api/scope-stats) read it through the same loader, so they cannot disagree about which scopes are configured. A RELATIVE path resolves against the directory holding THIS config.json, never the process working directory, so both processes find the same file. Env override: HASH_REGIONS_PATH, which wins over this key. If the path is set but the file is missing or not a JSON array of strings, the error is logged and the inline hashRegions list is used; on the ingestor's SIGHUP reload the previous keys are kept instead. A SIGHUP re-reads the file, so adding a region needs no restart. Names are case-sensitive: \"#dk\" and \"#DK\" are different scopes with different keys.",
  "_comment_defaultRegion": "IATA code shown by default in region filters.",
  "_comment_mapDefaults": "Initial map center [lat, lon] and zoom level.",
  "_comment_regions": "IATA code → display name mapping for the region filter UI. Each key is a 3-letter IATA code that an observer is tagged with (resolved priority: MQTT payload `region` field > topic-derived region > mqttSources.region). Observers without an IATA tag will not appear under any region filter — only under 'All Regions'. The region filter dropdown shows one entry per code listed here PLUS any extra IATA codes the server discovers from observers at runtime (so you can omit codes here and they will still be selectable, just labelled with the bare IATA code instead of a friendly name). Selecting 'All Regions' (or no region) returns results from every observer including those with no IATA tag; selecting one or more codes restricts results to packets observed by observers tagged with those codes. The reserved value 'All' (case-insensitive) is treated as 'no filter' on the server, so the URL ?region=All behaves identically to omitting the param. Issue #770.",

  "analytics": {
    "defaultIntervalSeconds": 300,
    "recomputeIntervalSeconds": {
      "topology": 300,
      "rf": 300,
      "distance": 300,
      "channels": 300,
      "hashCollisions": 300,
      "hashSizes": 300,
      "roles": 300,
      "observersClockSkew": 300,
      "nodesClockSkew": 300
    },
    "loraPreset": {
      "freq": 869600000,
      "bw": 62.5,
      "sf": 8,
      "cr": 5,
      "_comment_": "Issue #1768. LoRa PHY preset assumed by the Relay Airtime Share metric to compute true Time-on-Air. Share numbers are only meaningful relative to one preset, so operators MUST set this to match their mesh — freq is informational (surfaces in the chart caption) and does not affect ToA; bw is bandwidth in kHz (e.g. 62.5, 125, 250); sf is spreading factor (6..12); cr is the denominator of the 4/N coding rate (5 ⇒ 4/5 … 8 ⇒ 4/8). Defaults reproduce the typical EU MeshCore deployment 869.6 MHz / BW 62.5 kHz / SF 8 / CR 4/5. CRC=1, IH=0, DE (T_sym ≥ 16 ms), and preamble (32 for SF≤8, 16 otherwise, per firmware preambleLengthForSF) are firmware-fixed and intentionally not exposed as config."
    }
  },
  "_comment_analytics": "Issue #1240 + #1256 + #1265. Each analytics endpoint (topology, rf, distance, channels, hashCollisions, hashSizes, roles, observersClockSkew, nodesClockSkew) is recomputed in the background on the configured interval and served from an atomic-pointer cache. Reads never block on compute. Default 300s (5 min) per endpoint reflects the operator principle: serving slightly stale data quickly beats real-time data slowly. Lower values = fresher data at higher CPU cost. Only the default query (no region/window) is precomputed; region- and window-filtered requests fall back to the legacy on-request compute + 60s TTL cache.",
  "customizer": {
    "disabledTabs": [],
    "_comment_disabledTabs": "Issue #1508. List of customizer-modal tab ids to hide from end users. Useful when operators want to expose only daily-use viewer controls and keep one-shot admin chrome out of the way. Recognized ids: branding, theme, nodes, home, display, geofilter, export. Example: [\"branding\", \"geofilter\", \"export\"] hides the admin tabs and leaves theme/colors/home/display visible. Default [] keeps the legacy behavior (all tabs visible). Operators edit this in config.json directly — there is no in-app UI for this list (by design)."
  },
  "privacy": {
    "enabled": false,
    "_comment": "Opt-in privacy-notice page at #/privacy. Default off; set enabled=true to publish the page and the nav links that point at it. This flag is the ENTIRE privacy configuration -- the notice itself is a FIXED document in public/privacy.js and is deliberately not operator-editable, so the published wording cannot drift from the notice that was reviewed and signed off. Nothing you can put in config.json adds, removes or rewords a single line of it; changing the notice means editing that file. Older configs may still contain the removed text fields (controllerName, purposesText, retentionText and the rest) -- they are ignored, not rejected. None of this is legal advice, and publishing the page does not by itself make a deployment compliant."
  }
}