diff --git a/claude_desktop/CHANGELOG.md b/claude_desktop/CHANGELOG.md index 76c3d84b01..1e2f339180 100644 --- a/claude_desktop/CHANGELOG.md +++ b/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. diff --git a/claude_desktop/README.md b/claude_desktop/README.md index 597d9ea9bb..6dd6289446 100644 --- a/claude_desktop/README.md +++ b/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://: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 diff --git a/claude_desktop/config.yaml b/claude_desktop/config.yaml index d8fb6af705..819c429dc6 100644 --- a/claude_desktop/config.yaml +++ b/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 diff --git a/claude_desktop/rootfs/etc/s6-overlay/s6-rc.d/svc-headroom/run b/claude_desktop/rootfs/etc/s6-overlay/s6-rc.d/svc-headroom/run index 1389abfc71..a69b46aeda 100755 --- a/claude_desktop/rootfs/etc/s6-overlay/s6-rc.d/svc-headroom/run +++ b/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://: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)" - exec headroom proxy --host 127.0.0.1 --port "${port}" --code-aware + 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 "${host}" --port "${port}" --code-aware fi bashio::log.info "svc-headroom: install_headroom disabled or headroom not found; idling"