docs(claude_desktop): document Selkies ingress fix

claude_desktop/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.31 (16-07-2026)
+
+- Fix Home Assistant ingress remaining on `Waiting for stream`: current Selkies WebSocket mode connects through `/api/websockets`, while the add-on inherited an older nginx template that proxied only `/websocket`. Replace the template rewrite with an explicit ingress server that proxies `/api/` to Selkies on port 8082, retains `/websocket` compatibility, and declares `ingress_port: 3001` so nginx always receives a valid listen port.
+
 ## 1.30 (16-07-2026)
 
 - Compress large tool outputs automatically in every Claude Code session with a managed `PostToolUse` hook (new `headroom_auto_compress` option, enabled by default). Desktop-spawned sessions (cowork/dispatch) pin `ANTHROPIC_BASE_URL` to the production endpoint (headroom #869), so the transparent proxy never sees their traffic and compression there depended entirely on the model remembering to call the `headroom` MCP tools per the CLAUDE.md guidance — in practice most large outputs went uncompressed. The new `/usr/local/bin/headroom-posttooluse-compress.py` hook fires on `Bash`/`Grep`/`Glob`/`WebFetch` results over ~4000 characters, compresses them with Headroom's rule-based pipeline (SmartCrusher and friends; the Kompress ML path is disabled because its background model load can never complete inside a short-lived hook process), and swaps the result in via `hookSpecificOutput.updatedToolOutput` with a retrieval marker appended. Originals are stored in the shared CCR SQLite store (`~/.headroom/ccr_store.db` — the same one the headroom MCP server reads), so `mcp__headroom__headroom_retrieve` always recovers the full output; savings are recorded to the durable ledger (client `posttooluse-hook`) and show up in the existing gains report. The hook fails open (any error leaves the tool output untouched), never touches `stderr` fields so error text reaches the model verbatim, skips anything below a 50-token savings floor, and is registered idempotently in `~/.claude/settings.json` only after a `--self-test` confirms the interpreter can import headroom; disabling the option (or Headroom) removes the managed entry without touching user-defined hooks. Measured on a representative Home Assistant `states` dump: 10781 -> 2964 tokens (73% saved) at ~1.7 s hook overhead, with sub-100 ms pass-through for small outputs.

claude_desktop/config.yaml

@@ -20,6 +20,7 @@ environment:
   TITLE: Claude Desktop
 image: ghcr.io/alexbelgium/claude_desktop-{arch}
 ingress: true
+ingress_port: 3001
 init: false
 hassio_api: true
 hassio_role: manager
@@ -111,5 +112,5 @@ slug: claude_desktop
 tmpfs: true
 udev: true
 url: https://github.com/alexbelgium/hassio-addons
-version: "1.30"
+version: "1.31"
 video: true

claude_desktop/rootfs/etc/cont-init.d/90-ingress.sh

@@ -4,34 +4,105 @@ set -e
 
 NGINX_CONFIG=/etc/nginx/sites-available/ingress.conf
 SUBFOLDER="$(bashio::addon.ingress_entry)"
+INGRESS_PORT="$(bashio::addon.ingress_port)"
+DOWNLOADS_PATH="${HOME:-/config}"
 
-# Ensure subfolder ends with a trailing slash (except for root)
+# Home Assistant normally strips the ingress prefix before forwarding to the add-on,
+# but keep the normalized value available for diagnostics and future-safe logging.
 if [[ -n "${SUBFOLDER}" && "${SUBFOLDER}" != "/" ]]; then
     [[ "${SUBFOLDER}" == */ ]] || SUBFOLDER="${SUBFOLDER}/"
 else
     SUBFOLDER="/"
 fi
 
-cp /defaults/default.conf "${NGINX_CONFIG}"
+# Claude Desktop exposes only 3001/tcp in config.yaml. Older Supervisor/bashio
+# combinations can return an empty ingress_port when it is not explicit, which would
+# make nginx write an invalid `listen` directive. Fall back to the declared port.
+if [[ -z "${INGRESS_PORT}" ]]; then
+    INGRESS_PORT="3001"
+fi
 
-# Keep only the first (non-SSL) server block
-awk -v n=2 '/^[[:space:]]*server[[:space:]]*\{/{n--} n>0' "${NGINX_CONFIG}" > tmpfile
-mv tmpfile "${NGINX_CONFIG}"
+DOWNLOADS_PATH="${DOWNLOADS_PATH%/}"
 
-# Disable IPv6 listeners for ingress proxying
-sed -i '/listen \[::\]/d' "${NGINX_CONFIG}"
+cat > "${NGINX_CONFIG}" <<EOF
+server {
+  listen ${INGRESS_PORT} default_server;
+  client_max_body_size 10M;
 
-# Adapt ports and upstream paths for Home Assistant ingress
-sed -i "s|3000|$(bashio::addon.ingress_port)|g" "${NGINX_CONFIG}"
-sed -i "s|SUBFOLDER|/|g" "${NGINX_CONFIG}"
-sed -i "s|CWS|8082|g" "${NGINX_CONFIG}"
-sed -i "s|REPLACE_HOME|${HOME:-/root}|g" "${NGINX_CONFIG}"
-sed -i "s|REPLACE_DOWNLOADS_PATH|${HOME:-/config}|g" "${NGINX_CONFIG}"
-sed -i '/proxy_buffering/a proxy_set_header Accept-Encoding "";' "${NGINX_CONFIG}"
-sed -i '/proxy_buffering/a sub_filter_once off;' "${NGINX_CONFIG}"
-sed -i '/proxy_buffering/a sub_filter_types *;' "${NGINX_CONFIG}"
-sed -i '/proxy_buffering/a sub_filter "vnc/index.html?autoconnect" "vnc/index.html?path=%%path%%/websockify?autoconnect";' "${NGINX_CONFIG}"
-sed -i "s|%%path%%|${SUBFOLDER:1}|g" "${NGINX_CONFIG}"
+  location / {
+    alias /usr/share/selkies/web/;
+    index index.html index.htm;
+    try_files \$uri \$uri/ /index.html;
+  }
+
+  location /devmode {
+    proxy_set_header        Upgrade \$http_upgrade;
+    proxy_set_header        Connection "upgrade";
+    proxy_set_header        Host \$host;
+    proxy_set_header        X-Real-IP \$remote_addr;
+    proxy_set_header        X-Forwarded-For \$proxy_add_x_forwarded_for;
+    proxy_set_header        X-Forwarded-Proto \$scheme;
+    proxy_http_version      1.1;
+    proxy_read_timeout      3600s;
+    proxy_send_timeout      3600s;
+    proxy_connect_timeout   3600s;
+    proxy_buffering         off;
+    proxy_set_header        Accept-Encoding "";
+    proxy_pass              http://127.0.0.1:5173;
+  }
+
+  # Current Selkies WebSocket mode connects to <base>/api/websockets.
+  # The older linuxserver default.conf only proxies /websocket, leaving the
+  # dashboard loaded but stuck on "waiting for stream" under Home Assistant ingress.
+  location /api/ {
+    proxy_set_header        Upgrade \$http_upgrade;
+    proxy_set_header        Connection "upgrade";
+    proxy_set_header        Host \$host;
+    proxy_set_header        X-Real-IP \$remote_addr;
+    proxy_set_header        X-Forwarded-For \$proxy_add_x_forwarded_for;
+    proxy_set_header        X-Forwarded-Proto \$scheme;
+    proxy_http_version      1.1;
+    proxy_read_timeout      3600s;
+    proxy_send_timeout      3600s;
+    proxy_connect_timeout   3600s;
+    proxy_buffering         off;
+    proxy_set_header        Accept-Encoding "";
+    proxy_pass              http://127.0.0.1:8082;
+  }
+
+  # Keep compatibility with older Selkies/noVNC clients and linuxserver templates.
+  location /websocket {
+    proxy_set_header        Upgrade \$http_upgrade;
+    proxy_set_header        Connection "upgrade";
+    proxy_set_header        Host \$host;
+    proxy_set_header        X-Real-IP \$remote_addr;
+    proxy_set_header        X-Forwarded-For \$proxy_add_x_forwarded_for;
+    proxy_set_header        X-Forwarded-Proto \$scheme;
+    proxy_http_version      1.1;
+    proxy_read_timeout      3600s;
+    proxy_send_timeout      3600s;
+    proxy_connect_timeout   3600s;
+    proxy_buffering         off;
+    proxy_set_header        Accept-Encoding "";
+    proxy_pass              http://127.0.0.1:8082;
+  }
+
+  location /files {
+    fancyindex on;
+    fancyindex_footer /nginx/footer.html;
+    fancyindex_header /nginx/header.html;
+    alias ${DOWNLOADS_PATH}/;
+    if (-f \$request_filename) {
+      add_header Content-Disposition "attachment";
+      add_header X-Content-Type-Options "nosniff";
+    }
+  }
+
+  error_page 500 502 503 504 /50x.html;
+  location = /50x.html {
+    root /usr/share/selkies/web/;
+  }
+}
+EOF
 
-# Avoid content encoding on proxied responses to keep Selkies happy (handled by proxy_set_header Accept-Encoding insertion above)
 cp "${NGINX_CONFIG}" /etc/nginx/sites-enabled