Expose Claude Desktop headroom dashboard

claude_desktop/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 1.8 (08-07-2026)
+
+- Expose the Headroom live savings dashboard on mapped port `8787` when `install_headroom` is enabled, while keeping the proxy local-only if the port mapping is disabled.
+- Map `8787/tcp` by default and document the dashboard URL.
+
 ## 1.7 (07-07-2026)
 
 - Add an hourly rtk + headroom token-savings report to the add-on log (`claude-gains-report.sh`, seeded via `/defaults/crontabs/root` and run by the base image's cron). Lets you confirm at a glance that both tools keep running and see accumulated gains — if the numbers stop growing, the tool has stopped working.

claude_desktop/README.md

@@ -25,6 +25,7 @@ Claude Desktop sign-in requires a claude.ai plan that supports the Desktop app.
 - Baked-in `git` and GitHub CLI (`gh`) with optional startup credential configuration.
 - Custom script support through the repository standard `claude_desktop.sh` script.
 - Optional bundled Claude Code optimization tools: headroom, rtk, and caveman.
+- Headroom dashboard exposed on mapped port `8787` when `install_headroom` is enabled.
 - Low-power defaults: GPU device mapping, `AUTO_GPU=1`, `SELKIES_FRAMERATE=30`, `/tmp` tmpfs, and `$HOME/.cache` redirected to `/tmp/cache`.
 
 ## Options
@@ -38,7 +39,7 @@ Claude Desktop sign-in requires a claude.ai plan that supports the Desktop app.
 | `DRINODE` | | Optional GPU device override for Selkies. |
 | `DNS_server` | `8.8.8.8` | DNS server used by the standard DNS module. |
 | `auto_update` | `true` | Check Anthropic's apt repository and upgrade `claude-desktop` at add-on startup. |
-| `install_headroom` | `true` | Register the baked-in `headroom` MCP server in Claude Desktop, exposing its `headroom_compress`/`headroom_retrieve`/`headroom_stats` context-compression tools inside the app. (Claude Desktop overrides `ANTHROPIC_BASE_URL`, so transparent proxy compression is not possible — MCP is the supported path; see [headroom #869](https://github.com/headroomlabs-ai/headroom/issues/869).) Disabling removes the entry again. |
+| `install_headroom` | `true` | Register the baked-in `headroom` MCP server in Claude Desktop, start the Headroom proxy backend, and expose the Headroom dashboard on mapped port `8787` at `/dashboard` when that port is open. This exposes the `headroom_compress`/`headroom_retrieve`/`headroom_stats` context-compression tools inside the app. (Claude Desktop overrides `ANTHROPIC_BASE_URL`, so transparent proxy compression is not possible — MCP is the supported path; see [headroom #869](https://github.com/headroomlabs-ai/headroom/issues/869).) Disabling removes the MCP entry and stops the backend/dashboard service. |
 | `install_rtk` | `true` | Configure the rtk Claude Code `PreToolUse` hook in the persistent Claude Code settings. |
 | `install_caveman` | `true` | Install the caveman Claude Code plugin into the persistent Claude Code home. |
 | `install_github_cli` | `true` | Enable first-start checks and setup for the baked-in `git` and `gh` commands. |
@@ -63,6 +64,10 @@ The add-on includes the repository standard custom-script executor. On first sta
 
 Persistent state is stored in the configured `data_location`. Claude Desktop stores sign-in data below `~/.config/Claude`, and Claude Code/tool configuration is stored below `~/.claude`. Volatile cache data is redirected to `/tmp/cache` through `$XDG_CACHE_HOME` and `$HOME/.cache`.
 
+## Headroom dashboard
+
+When `install_headroom` is enabled, the add-on starts the local Headroom proxy backend and maps port `8787` by default. Open `http://<home-assistant-host>:8787/dashboard` to view the Headroom live savings dashboard. If you disable the `8787/tcp` port mapping, the backend binds to localhost for MCP use only and the dashboard is not externally exposed.
+
 [aarch64-shield]: https://img.shields.io/badge/aarch64-yes-green.svg
 [amd64-shield]: https://img.shields.io/badge/amd64-yes-green.svg
 [maintenance-shield]: https://img.shields.io/maintenance/yes/2026.svg

claude_desktop/config.yaml

@@ -54,8 +54,10 @@ panel_admin: false
 panel_icon: mdi:robot-happy
 ports:
   3001/tcp: null
+  8787/tcp: 8787
 ports_description:
   3001/tcp: Web interface https
+  8787/tcp: Headroom dashboard and proxy
 privileged:
   - SYS_ADMIN
   - DAC_READ_SEARCH
@@ -88,5 +90,5 @@ slug: claude_desktop
 tmpfs: true
 udev: true
 url: https://github.com/alexbelgium/hassio-addons
-version: "1.7"
+version: "1.8"
 video: true

claude_desktop/rootfs/etc/s6-overlay/s6-rc.d/svc-headroom/run

@@ -6,10 +6,19 @@
 # client are unaffected. Without this backend the MCP tools cannot store/retrieve compressed
 # content and no savings are ever recorded.
 declare port=8787
+declare host=127.0.0.1
+
+# Expose the built-in Headroom dashboard only when the add-on option is enabled
+# and Home Assistant has mapped the Headroom port. The port is mapped by default
+# in config.yaml, so users can open http://<ha-host>:8787/dashboard to inspect
+# live savings, while disabling install_headroom still leaves the service idle.
+if [[ -n "$(bashio::addon.port "${port}")" ]]; then
+    host=0.0.0.0
+fi
 
 if bashio::config.true 'install_headroom' && command -v headroom >/dev/null 2>&1; then
-    bashio::log.info "svc-headroom: starting headroom proxy on 127.0.0.1:${port} (MCP backend only; no client routing)"
+    bashio::log.info "svc-headroom: starting headroom proxy on ${host}:${port}; dashboard available at /dashboard when the port is mapped (MCP backend only; no client routing)"
-    exec headroom proxy --host 127.0.0.1 --port "${port}" --code-aware
+    exec headroom proxy --host "${host}" --port "${port}" --code-aware
 fi
 
 bashio::log.info "svc-headroom: install_headroom disabled or headroom not found; idling"