Merge branch 'feat/9-reverse-proxy-config-override'

Reverse-proxy/tunnel options (alias_port etc.) and config_override,
extracted from PR #9 without the OIDC feature (kept separate as #8).

Closes #9.

Author: andlo

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## \[0.2.14\] - 2026-07-26
+
+### Added
+
+- **Reverse proxy / tunnel options** — makes MeshCentral fully usable behind Cloudflare Tunnel, NGINX Proxy Manager, Traefik, etc. (thanks @ddcash):
+  - `alias_port` — the publicly visible HTTPS port (e.g. `443` behind Cloudflare Tunnel). Without it, agent installers point at port 4430 and agents behind a proxy can never connect.
+  - `agent_alias_port` / `agent_alias_dns` — same aliasing for the dedicated agent port
+  - `agent_pong` / `browser_pong` — WebSocket keepalive intervals; needed behind proxies that drop idle connections (Cloudflare: ~100 s)
+- `minify` — serve reduced-size web pages
+- `config_override` — advanced: raw JSON object deep-merged on top of the generated config.json as the last step, making every MeshCentral setting reachable even without a dedicated add-on option
+
 ## \[0.2.13\] - 2026-07-10
 
 ### Added

meshcentral/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## \[0.2.14\] - 2026-07-26
+
+### Added
+
+- **Reverse proxy / tunnel options** — makes MeshCentral fully usable behind Cloudflare Tunnel, NGINX Proxy Manager, Traefik, etc. (thanks @ddcash):
+  - `alias_port` — the publicly visible HTTPS port (e.g. `443` behind Cloudflare Tunnel). Without it, agent installers point at port 4430 and agents behind a proxy can never connect.
+  - `agent_alias_port` / `agent_alias_dns` — same aliasing for the dedicated agent port
+  - `agent_pong` / `browser_pong` — WebSocket keepalive intervals; needed behind proxies that drop idle connections (Cloudflare: ~100 s)
+- `minify` — serve reduced-size web pages
+- `config_override` — advanced: raw JSON object deep-merged on top of the generated config.json as the last step, making every MeshCentral setting reachable even without a dedicated add-on option
+
 ## \[0.2.13\] - 2026-07-10
 
 ### Added

meshcentral/config.yaml

@@ -1,6 +1,6 @@
 {
   "name": "MeshCentral",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "slug": "meshcentral",
   "description": "Self-hosted remote device management — monitor and control your PCs from Home Assistant",
   "url": "https://github.com/andlo/ha-meshcentral-addon",
@@ -48,6 +48,12 @@
     "agent_allowed_ip": "",
     "agent_blocked_ip": "",
     "agent_port": 0,
+    "alias_port": 0,
+    "agent_alias_port": 0,
+    "agent_alias_dns": "",
+    "agent_pong": 0,
+    "browser_pong": 0,
+    "minify": false,
     "mps_port": 4433,
     "backup_interval_hours": 24,
     "backup_keep_days": 10,
@@ -58,7 +64,8 @@
     "smtp_from": "",
     "smtp_user": "",
     "smtp_pass": "",
-    "smtp_tls": true
+    "smtp_tls": true,
+    "config_override": ""
   },
   "schema": {
     "server_mode": "list(lan|wan|hybrid)",
@@ -90,6 +97,12 @@
     "agent_allowed_ip": "str?",
     "agent_blocked_ip": "str?",
     "agent_port": "int",
+    "alias_port": "int",
+    "agent_alias_port": "int",
+    "agent_alias_dns": "str?",
+    "agent_pong": "int",
+    "browser_pong": "int",
+    "minify": "bool",
     "mps_port": "int",
     "backup_interval_hours": "int",
     "backup_keep_days": "int",
@@ -100,7 +113,8 @@
     "smtp_from": "str?",
     "smtp_user": "str?",
     "smtp_pass": "password?",
-    "smtp_tls": "bool?"
+    "smtp_tls": "bool?",
+    "config_override": "str?"
   },
   "map": [
     "data:rw",

meshcentral/run.sh

@@ -25,6 +25,11 @@ MPS_PORT=$(bashio::config 'mps_port')
 BACKUP_INTERVAL=$(bashio::config 'backup_interval_hours')
 BACKUP_KEEP=$(bashio::config 'backup_keep_days')
 SMTP_ENABLED=$(bashio::config 'smtp_enabled')
+ALIAS_PORT=$(bashio::config 'alias_port')
+AGENT_ALIAS_PORT=$(bashio::config 'agent_alias_port')
+AGENT_PONG=$(bashio::config 'agent_pong')
+BROWSER_PONG=$(bashio::config 'browser_pong')
+MINIFY=$(bashio::config 'minify')
 
 # ── Paths ─────────────────────────────────────────────────────────────────────
 # Everything lives in the add-on config folder (/addon_configs/<slug>, mounted
@@ -84,6 +89,28 @@ if [ "$AGENT_PORT" -gt 0 ] 2>/dev/null; then
     SETTINGS=$(echo "$SETTINGS" | jq --argjson v "$AGENT_PORT" '. + {agentPort: $v}')
 fi
 
+# Alias ports — the publicly visible ports when behind a reverse proxy or tunnel
+# that listens on a different port than MeshCentral itself (e.g. Cloudflare on 443).
+# These control the port written into agent installers and links.
+if [ "$ALIAS_PORT" -gt 0 ] 2>/dev/null; then
+    SETTINGS=$(echo "$SETTINGS" | jq --argjson v "$ALIAS_PORT" '. + {aliasPort: $v}')
+fi
+if [ "$AGENT_ALIAS_PORT" -gt 0 ] 2>/dev/null; then
+    SETTINGS=$(echo "$SETTINGS" | jq --argjson v "$AGENT_ALIAS_PORT" '. + {agentAliasPort: $v}')
+fi
+if bashio::config.has_value 'agent_alias_dns'; then
+    SETTINGS=$(echo "$SETTINGS" | jq --arg v "$(bashio::config 'agent_alias_dns')" '. + {agentAliasDNS: $v}')
+fi
+
+# Keepalive intervals — needed behind proxies that drop idle WebSockets
+# (e.g. Cloudflare closes idle connections after ~100 seconds).
+if [ "$AGENT_PONG" -gt 0 ] 2>/dev/null; then
+    SETTINGS=$(echo "$SETTINGS" | jq --argjson v "$AGENT_PONG" '. + {agentPong: $v}')
+fi
+if [ "$BROWSER_PONG" -gt 0 ] 2>/dev/null; then
+    SETTINGS=$(echo "$SETTINGS" | jq --argjson v "$BROWSER_PONG" '. + {browserPong: $v}')
+fi
+
 # Cert / hostname
 if bashio::config.has_value 'cert_url'; then
     CERT_HOST=$(bashio::config 'cert_url' | sed 's|https://||' | sed 's|http://||' | sed 's|/.*||')
@@ -192,6 +219,10 @@ if bashio::config.has_value 'cert_url'; then
     DOMAIN=$(echo "$DOMAIN" | jq --arg v "$(bashio::config 'cert_url')" '. + {certUrl: $v}')
 fi
 
+if [ "$MINIFY" = "true" ]; then
+    DOMAIN=$(echo "$DOMAIN" | jq '. + {minify: true}')
+fi
+
 DOMAIN=$(echo "$DOMAIN" | jq --arg rp "$RECORDINGS_PATH" \
     '. + {sessionRecording: {filepath: $rp}}')
 
@@ -228,6 +259,19 @@ else
         '{settings: $settings, domains: {"": $domain}, smtp: $smtp}')
 fi
 
+# ── Apply raw JSON overrides (advanced) ───────────────────────────────────────
+# config_override is deep-merged on top of the generated config as the last step,
+# so any MeshCentral setting can be reached even if the add-on has no option for it.
+if bashio::config.has_value 'config_override'; then
+    OVERRIDE=$(bashio::config 'config_override')
+    if echo "$OVERRIDE" | jq -e 'type == "object"' >/dev/null 2>&1; then
+        CONFIG=$(jq -n --argjson base "$CONFIG" --argjson ovr "$OVERRIDE" '$base * $ovr')
+        bashio::log.info "config_override applied on top of the generated config."
+    else
+        bashio::log.warning "config_override is not a valid JSON object — ignored."
+    fi
+fi
+
 echo "$CONFIG" > "$CONFIG_FILE"
 bashio::log.info "config.json written."
 

meshcentral/translations/en.yaml

@@ -176,6 +176,44 @@ configuration:
       Optional separate HTTPS port exclusively for agent connections.
       Set to 0 (default) to use the main port (4430) for everything.
 
+  alias_port:
+    name: Public alias port
+    description: >-
+      The publicly visible HTTPS port when MeshCentral runs behind a reverse proxy or tunnel
+      that listens on a different port (e.g. set to 443 behind Cloudflare Tunnel or NGINX on 443).
+      Controls the port written into agent installers and links. Set to 0 (default) to disable.
+
+  agent_alias_port:
+    name: Agent alias port
+    description: >-
+      The publicly visible port for the dedicated agent port, when a reverse proxy in front of it
+      listens on a different port. Only relevant when a dedicated agent port is set.
+      Set to 0 (default) to disable.
+
+  agent_alias_dns:
+    name: Agent alias DNS name
+    description: >-
+      Optional DNS name agents use to connect to the dedicated agent port, if different
+      from the main hostname. Leave empty to use the main hostname.
+
+  agent_pong:
+    name: Agent keepalive interval (seconds)
+    description: >-
+      Send keepalive data to connected agents every this many seconds. Needed behind proxies
+      that drop idle WebSocket connections — e.g. set to 60 behind Cloudflare, which closes
+      idle connections after about 100 seconds. Set to 0 (default) to disable.
+
+  browser_pong:
+    name: Browser keepalive interval (seconds)
+    description: >-
+      Send keepalive data to connected browsers every this many seconds. Same purpose as the
+      agent keepalive, but for web sessions. Set to 0 (default) to disable.
+
+  minify:
+    name: Minify web pages
+    description: >-
+      Serve reduced-size web pages to save bandwidth. Disabled by default.
+
   mps_port:
     name: Intel AMT / MPS port
     description: >-
@@ -235,3 +273,11 @@ configuration:
     description: >-
       Enable TLS/STARTTLS for the SMTP connection. Should be enabled for port 587.
       Disable only if your SMTP server does not support TLS.
+
+  config_override:
+    name: Config override (advanced, raw JSON)
+    description: >-
+      Advanced — a JSON object deep-merged on top of the generated config.json as the last step.
+      Lets you set any MeshCentral option the add-on does not expose
+      (e.g. {"settings":{"sessionRecording":true}}). Invalid JSON is ignored with a warning.
+      See the MeshCentral config schema for all available settings.