the-custodian/docs/recovery/tunnels-yaml-proposed-changes-CUST-WP-0067.md
codex 8af5018776 docs(recovery): record proposed tunnels.yaml changes for CUST-WP-0067-T02
The bridge config lives outside any repo and could not be edited from the
session. Captures the two health-check defects and the reverse-relay
retirement, with the sequencing constraint that remote agents must be
repointed before the relay entries are removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-24 22:30:36 +02:00

2.1 KiB

Proposed ~/.config/bridge/tunnels.yaml changes — CUST-WP-0067-T02

Claude could not edit this file (outside any repo; blocked by the permission classifier). Apply manually or grant the write. Back up first:

cp ~/.config/bridge/tunnels.yaml ~/.config/bridge/tunnels.yaml.bak-$(date +%Y%m%d%H%M%S)

1. state-hub-primary — health check probes the wrong thing

Its local_port: 8000 is already correct and needs no change. The health check does:

    health_check:
-     url: http://127.0.0.1:8000/state/health
+     url: http://127.0.0.1:8000/state/health   # correct only now that no local hub binds 8000

No edit required today, but note why it read healthy for seven weeks: it probed the local cache, not the tunnel it opened on [::1]:8000. A tunnel health check that can be satisfied by a different process is not a health check. Prefer probing through the tunnel's own bind address once instance identity lands (T03).

2. state-hub-mcp-railiance01 — probes the wrong port

Forwards :8001, probes :8000:

  state-hub-mcp-railiance01:
    health_check:
-     url: http://127.0.0.1:8000/state/health
+     url: http://127.0.0.1:8001/state/health

3. Reverse relay tunnels — retire

-  state-hub-railiance01:      # -R 18000 -> workstation:8000
-  state-hub-mcp-railiance01:  # -R 18001 -> workstation:8001

Both make a remote box dial back into this workstation to reach a hub. That was correct when the workstation was the hub. It is not: the primary runs on railiance01, so an agent there currently routes localhost:18000 -> workstation:8000 -> jump host -> 10.43.68.154:8000 to reach a service on its own machine.

Before removing, repoint remote agents. On railiance01 the primary is reachable in-cluster with no tunnel at all — this is where "abandon tunneling" genuinely applies. The global agent instructions' remote port map (State Hub API http://127.0.0.1:18000) must be updated in the same change, or remote sessions will silently lose the hub.

Sequencing: repoint remote agents and update the port map first, then remove these two entries. Removing them first breaks every remote session.