feat(dashboard): add durable service support

[LukasParke]

What does this PR do?

Adds durable, installable service support for the Hermes web dashboard, matching the gateway's host-service workflow while keeping the dashboard loopback-bound by default.

This gives operators a first-class way to run the dashboard persistently under systemd, launchd, or a Windows Scheduled Task, plus secure remote-access helpers for Tailscale/headscale Serve and cloudflared. It also adds explicit dashboard Host-header allowlisting so loopback-bound dashboards can sit behind trusted local proxies/tunnels without disabling DNS-rebinding protection.

This builds on the new dashboard administration surface from #36704. Because the dashboard can now administer MCP, credentials, gateway lifecycle, memory, webhooks, and ops tasks, this PR keeps the default exposure model conservative: 127.0.0.1 by default, OAuth gate behavior preserved for public binds, and explicit allowlists for proxy hostnames.

Related Issue

Fixes #34390

Related follow-up/risk context:

• Dashboard hangs: tui_gateway.slash_worker subprocesses leak on PTY chat disconnect (524 via reverse proxy) #32377 / Dashboard: leaked tui_gateway.slash_worker processes accumulate, exhaust file descriptors on macOS launchd #24775 — durable dashboard services make PTY/slash-worker cleanup more important.
• [Bug]: hermes update leaves web/node_modules in broken state — dashboard service crash-loops with lucide-react resolve + missing tsc #34312 / Optimization: Robust update process for hermes update #34335 — service startup depends on a valid prebuilt dashboard dist when using --skip-build.
• [Bug] Kanban DB corruption when gateway and dashboard open the same board DB concurrently (WAL mode) #33169 — durable dashboard + gateway side-by-side can make existing Kanban DB concurrency issues easier to hit.
• feat(dashboard): full administration panel — MCP, pairing, webhooks, credentials, memory, gateway, ops #36704 — this PR adds durable service/access support for the full dashboard admin panel introduced there.

Consolidated Related PR Content

#34390 was marked as part of the larger dashboard reverse-proxy Host-header allowlisting cluster. This PR consolidates the operator-facing Host-header / reverse-proxy portions of that cluster into the broader durable dashboard service/access feature, instead of landing another narrow allowlist-only variant.

Fully consolidated by this PR:

• feat(dashboard): add --allowed-host flag for reverse proxy support #20884 — CLI-only --allowed-host support for Tailscale / reverse-proxy Host headers. Covered by hermes dashboard --allowed-hosts, plus service install/unit propagation.
• fix: support reverse proxy domains via HERMES_DASHBOARD_EXTRA_HOSTS env var #22437 — env-var reverse-proxy domains via HERMES_DASHBOARD_EXTRA_HOSTS. Covered by HERMES_DASHBOARD_ALLOWED_HOSTS, with additional config and CLI surfaces.
• fix(dashboard): allow reverse proxy hosts #25173 — env-var Host-header allowlisting and focused allowed-host tests. Covered by normalized dashboard allowed hosts and the host-header test suite.
• feat(dashboard): allow trusted reverse-proxy Host headers #27113 — trusted reverse-proxy Host headers via HERMES_DASHBOARD_ALLOWED_HOSTS, Host normalization, docs, and Tailscale Serve guidance. Covered by the same env var, plus config/CLI/service support.
• fix: allow dashboard host headers for trusted proxies #28954 — CLI/config allowed hosts for Cloudflare Access / Tunnel and loopback origin deployments. Covered by --allowed-hosts, dashboard.allowed_hosts, service persistence, and cloudflared config/service helpers.
• feat(dashboard): allow extra hostnames in Host validator via env var #29195 — narrow additional-hosts env-var use case for loopback-bound Tailscale Serve / reverse-proxy access. Covered by the env/config/CLI allowed-host surface, loopback-only allowed-host semantics, and HTTP + WebSocket Host/Origin checks.
• fix(dashboard): allow explicit proxy hostnames #31304 — explicit proxy hostnames plus Tailscale/reverse-proxy documentation angle. Covered by allowed-hosts support and updated dashboard docs.
• Allow reverse-proxied hostnames via dashboard --trusted-host allowlist #32109 — repeatable --trusted-host / HERMES_DASHBOARD_TRUSTED_HOSTS style trusted hostname allowlist. Covered by the single --allowed-hosts / HERMES_DASHBOARD_ALLOWED_HOSTS naming surface.
• [Feature] dashboard: add --allowed-hosts flag for reverse-proxy and Tailscale access #34390 — direct issue request for --allowed-hosts with Tailscale Serve and reverse proxies. Covered by direct dashboard runs and persisted service installs.

Related but not fully consolidated by this PR:

• fix(dashboard): validate WebSocket proxy peers and origins #20136 — this PR covers dashboard HTTP and WebSocket Host/Origin allowlisting, but does not add the CIDR-based WebSocket peer allowlist / dashboard.trusted_proxy_hosts model from fix(dashboard): validate WebSocket proxy peers and origins #20136.
• [codex] Fix dashboard chat and browser voice over Tailscale #20871 — the Tailscale/reverse-proxy dashboard chat access portion is covered; the browser voice transcription/synthesis features are intentionally not included.
• fix(web-dashboard): i18n types + reverse-proxy host allowlist #28578 — the Host-header allowlist/docs portion is covered; the unrelated i18n scheduled type fix is intentionally not included.
• Add dashboard TLS and allowed-host flags #29959 — the allowed-host flag content is covered; direct HTTPS serving via --tls-cert / --tls-key is intentionally not included because this PR focuses on loopback plus trusted tunnel/proxy access.
• feat(dashboard): allow Tailscale Serve identity auth via dashboard.tailscale_allowlist #20515 — Tailscale identity-header authentication is a different auth model and is not included.
• fix: support proxied dashboard chat sessions #21104 — proxy-header, TUI bundle freshness, and session-list fixes are adjacent dashboard reliability work but are not part of this service/access PR.
• fix(web): allow WebSocket connections from remote clients when --insecure is used #17440 / fix(cli): honor --insecure for dashboard WebSocket connections #17887 / feat(cli): add --insecure-chat flag for non-loopback WS chat clients #15736 — older --insecure non-loopback WebSocket fixes were already addressed on main; this PR preserves that path but does not add a separate --insecure-chat flag.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• Added hermes_cli/dashboard_service.py:
  • systemd user/system unit generation and lifecycle
  • macOS launchd plist generation and lifecycle
  • Windows Scheduled Task wrapper generation and lifecycle
  • persisted dashboard service install options under $HERMES_HOME/dashboard-service/config.json
  • Tailscale/headscale Serve command generation/apply helper
  • cloudflared tunnel config generation and native service helper
• Extended hermes dashboard CLI:
  • hermes dashboard service install|start|stop|restart|status|uninstall|unit
  • hermes dashboard access tailscale-serve
  • hermes dashboard access cloudflare-config
  • hermes dashboard access cloudflare-service ...
  • --allowed-hosts for direct dashboard runs
• Added dashboard Host-header allowlisting:
  • CLI: --allowed-hosts
  • config: dashboard.allowed_hosts
  • env: HERMES_DASHBOARD_ALLOWED_HOSTS
  • applies to HTTP and WebSocket Host/Origin checks
• Added authenticated dashboard admin endpoints:
  • dashboard service status/install/start/stop/restart/uninstall
  • Tailscale Serve apply
  • cloudflared config generation/service actions
• Updated the System page with dashboard service and secure access controls.
• Updated API types/client methods and web dashboard / CLI docs.
• Added focused tests for service generation, access helpers, Host allowlisting, WebSocket allowlisting, and admin endpoints.

How to Test

1. Generate a service definition:

   hermes dashboard service unit \
     --host 127.0.0.1 \
     --port 9119 \
     --allowed-hosts device.tailnet.ts.net \
     --public-url https://device.tailnet.ts.net

2. Print secure-access helper commands/config:

   hermes dashboard access tailscale-serve --port 9119
   hermes dashboard access cloudflare-config \
     --tunnel t123 \
     --credentials-file /tmp/t.json \
     --hostname dash.example.com \
     --port 9119

3. Run focused verification:

   python -m py_compile hermes_cli/dashboard_service.py hermes_cli/main.py hermes_cli/web_server.py
   uv run --frozen --with pytest --with pytest-timeout pytest tests/hermes_cli/test_dashboard_service.py
   uv run --frozen --with pytest --with pytest-timeout pytest tests/hermes_cli/test_web_server_host_header.py tests/hermes_cli/test_dashboard_admin_endpoints.py
   cd web && bun run build
   git diff --check

Observed results after resolving the latest origin/main merge and cleanup:

• python -m py_compile hermes_cli/web_server.py tests/hermes_cli/test_web_server_host_header.py: passed
• uv run --frozen --with pytest --with pytest-timeout pytest tests/hermes_cli/test_web_server_host_header.py tests/hermes_cli/test_dashboard_service.py tests/hermes_cli/test_dashboard_admin_endpoints.py: 62 passed, 1 existing audioop deprecation warning from discord/player.py
• web production build passed, with the existing large chunk warning
• git diff --check passed

Not run:

• Full pytest tests/ -q. The focused dashboard/service/web tests above were run instead.
• Native macOS launchd and Windows Scheduled Task execution. Those paths are covered by generation/unit tests and mirror the gateway service patterns, but were not executed on those platforms in this checkout.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Linux

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

No screenshots. This is primarily CLI/service/API wiring plus the System page controls.

[teknium1]

Thanks for consolidating durable dashboard-service work with the real reverse-proxy/Tailscale Host-header problem documented in #34390.

Problems

• The new loopback allowlist accepts an external Host at hermes_cli/web_server.py:251, but current main derives app.state.auth_required only from the bind address at hermes_cli/web_server.py:17015. An allowed proxy hostname on a loopback bind must force the auth gate, and that condition must also feed the interactive setup preflight.
• HERMES_DASHBOARD_ALLOWED_HOSTS is a new non-secret behavioral setting. AGENTS.md:102-107 requires this policy to live in dashboard.allowed_hosts in config.yaml, not .env/environment configuration.
• The new hermes_cli/dashboard_service.py embeds Tailscale and cloudflared management (build_tailscale_serve_command, _cloudflared_service_command), conflicting with the third-party integration boundary in AGENTS.md:126-136.
• The branch is conflicting, and its parser edits target the old inline main.py implementation; current main's dashboard parser lives in hermes_cli/subcommands/dashboard.py:17-156.

Suggested changes

• Share an effective-auth predicate between startup and preflight; add loopback-plus-allowlist HTTP/WS tests.
• Keep the persistent allowlist in dashboard.allowed_hosts, remove the new env-var path, and separate vendor-specific tunnel management from the core service implementation.

This is an automated hermes-sweeper review.

[teknium1]

Allowlisting an external Host on a loopback bind also needs to engage the dashboard auth gate. Current main derives app.state.auth_required only from the bind host (start_server), so this makes a proxy-reachable loopback dashboard accept the external origin while remaining ungated. Please share an effective-auth predicate with startup and the interactive preflight, and add a loopback-plus-allowlist regression test.