docs: document the agent-relayed console proxy

Every console session now rides the agent's outbound gRPC connection instead of a direct guacd-to-target dial, so it works for servers behind NAT and now requires a live agent (409 agent_offline otherwise). Documents PROXY_ADVERTISE_HOST / PROXY_LISTEN_HOST and corrects reachability claims across the docsite and CLAUDE.md.
2026-07-31 09:10:05 +01:00
parent 119d8694d1
commit 1e1546cb60
5 changed files with 42 additions and 13 deletions
@@ -17,6 +17,8 @@ it is absent.
 | `KEY_ENCRYPTION_KEY`       | yes in practice |                             | 64 hex characters (32 bytes) for AES-256-GCM. Required for private keys, vault secrets, OIDC client secrets and console credentials                                |
 | `GITEA_HOST`               | yes             | `gitea.example.com`         | Used to build the install scripts and agent download URLs. The default is a placeholder that will not resolve                                                      |
 | `GUACD_ADDR`               | no              | `guacd:4822`                | The [browser console](../vantage/browser-console.md) daemon                                                                                                        |
+| `PROXY_ADVERTISE_HOST`     | no              | `server`                    | The hostname **guacd** uses to reach the control plane's console relay. Wrong here and every console session fails at connect with guacd unable to resolve the relay |
+| `PROXY_LISTEN_HOST`        | no              | `0.0.0.0`                   | Interface the ephemeral relay listeners bind. Narrow it only if guacd shares a known interface                                                                     |
 | `APP_ROOT_LABEL`           | no              | `vantage`                   | The app root label for the host and session organisation guard                                                                                                     |
 | `VANTAGE_WORKFLOW_LOG_DIR` | no              |                             | Where workflow run logs are written                                                                                                                                |

@@ -24,7 +24,8 @@ flowchart LR
    W --> S["server :8080"]
    A["Agent on a managed server"] -->|"gRPC/TLS :9090, outbound"| S
    S --> G["guacd :4822"]
-    G -->|"SSH / RDP / VNC"| T["Target machine"]
+    G -->|"relayed over the :9090 stream"| A
+    A -->|"SSH / RDP / VNC, loopback"| T["Target machine (same host as agent)"]
 ```

 Two things are worth reading off that diagram.
@@ -33,9 +34,13 @@ Two things are worth reading off that diagram.
 NAT is not an obstacle. The only requirement is that the machine can reach
 `GRPC_HOST`.

-**The console does not use the agent.** guacd connects directly to the target on
-the protocol port. A machine reachable only by its agent behind NAT, on a
-private subnet cannot be consoled, even though every other feature works.
+**The console rides the agent's connection too.** guacd never dials the target
+directly; the server pushes a command down the agent's existing outbound gRPC
+stream on `9090`, and the agent relays the protocol traffic from its own
+loopback. No route from the control plane to the target's address is needed,
+and no new inbound port opens on the target — the same connection that carries
+key sync carries console traffic. This is what makes the console work for a
+machine behind NAT on a private subnet, as long as its agent is online.

 ## What to open

@@ -49,7 +54,9 @@ private subnet cannot be consoled, even though every other feature works.
 - `gitea.hostxtra.co.uk`, for agent releases and version checks.
 - Anything a server-run [monitor](../vantage/monitors.md) checks.
 - SMTP, if you use an SMTP notification channel.
- Protocol ports on machines you intend to console.
+
+No route to the machines you intend to console is needed — that traffic rides
+the agent's existing outbound `9090` connection instead.

 ### Outbound from a managed machine

@@ -86,7 +86,7 @@ instantaneous.
 | Connects, then closes at once | guacd unreachable. Check `GUACD_ADDR` and that the container is running                                         |
 | SSH rejects the key           | The stored key has no private half, or is not on the target                                                     |
 | RDP fails on retry            | Credentials are single-use and consumed at tunnel open enter them again                                         |
-| Hangs at "connecting"         | The **control plane** cannot reach the target on the protocol port. The agent's reachability is irrelevant here |
+| Hangs at connecting            | The agent is offline, or nothing is listening on the protocol port on the target's own loopback address. Check the audit log for `console.proxy_failed` — its reason names which |
 | Fails only in production      | The reverse proxy is not forwarding WebSocket upgrade headers                                                   |

 ## Monitors report down when the service is up