Skip to content

Agent Mesh

standalone: the public URL is stated, not inferred from request headers

Antonio Ojea758f986cb873
diff --git a/internal/controlplane/config.go b/internal/controlplane/config.go
index d50af498..162a8053 100644
--- a/internal/controlplane/config.go
+++ b/internal/controlplane/config.go
@@ -86,9 +86,6 @@ type Options struct {
// STSRateBurst is the per-node burst size for /token/exchange and
// /sts/token (defaults to STSRateBurstDefault).
STSRateBurst int
- // TrustForwardedHeaders controls whether oidcIssuerURL trusts X-Forwarded-Proto
- // when STSIssuerURL is not explicitly configured.
- TrustForwardedHeaders bool
}
const (
diff --git a/internal/controlplane/sts.go b/internal/controlplane/sts.go
index 9be60ee6..898ab035 100644
--- a/internal/controlplane/sts.go
+++ b/internal/controlplane/sts.go
@@ -328,14 +328,19 @@ func isValidHostHeader(host string) bool {
return true
}
-// oidcIssuerURL returns the canonical OIDC issuer URL for this control plane.
+// oidcIssuerURL returns the canonical OIDC issuer URL for this control plane:
+// STSIssuerURL when the operator stated it, else this listener as the
+// request reached it. Nothing is read from X-Forwarded-* headers: behind a
+// TLS-terminating proxy the operator states the public URL (--sts-issuer-url,
+// or --external-url on agentmesh-one), so that the issuer is one value for
+// every client and not whatever a request claimed.
func (s *Server) oidcIssuerURL(r *http.Request) string {
if iss := strings.TrimRight(strings.TrimSpace(s.config.STSIssuerURL), "/"); iss != "" {
return iss
}
scheme := "http"
if r != nil {
- if r.TLS != nil || (s.config.TrustForwardedHeaders && strings.EqualFold(r.Header.Get("X-Forwarded-Proto"), "https")) {
+ if r.TLS != nil {
scheme = "https"
}
if host := strings.TrimSpace(r.Host); isValidHostHeader(host) {
diff --git a/internal/standalone/standalone.go b/internal/standalone/standalone.go
index 6ab1c7fa..80ab4a18 100644
--- a/internal/standalone/standalone.go
+++ b/internal/standalone/standalone.go
@@ -33,6 +33,7 @@ import (
"os"
"path/filepath"
"strings"
+ "sync"
"time"
"github.com/google/agentmesh/api"
@@ -42,10 +43,10 @@ import (
"github.com/google/agentmesh/internal/storage"
golog "github.com/ipfs/go-log/v2"
"github.com/libp2p/go-libp2p/core/crypto"
- "github.com/libp2p/go-libp2p/core/peer"
"github.com/multiformats/go-multiaddr"
+ "github.com/prometheus/client_golang/prometheus"
+ "github.com/prometheus/client_golang/prometheus/promauto"
"google.golang.org/protobuf/encoding/protojson"
- "google.golang.org/protobuf/proto"
)
var logger = golog.Logger("agentmesh-one")
@@ -731,187 +732,38 @@ func ensureRouterKey(keyPath, adminToken string) error {
return os.WriteFile(keyPath, data, 0o600)
}
-type responseRecorder struct {
- header http.Header
- body bytes.Buffer
- code int
-}
-
-func newResponseRecorder() *responseRecorder {
- return &responseRecorder{
- header: make(http.Header),
- code: http.StatusOK,
- }
-}
-
-func (r *responseRecorder) Header() http.Header {
- return r.header
-}
-
-func (r *responseRecorder) Write(b []byte) (int, error) {
- return r.body.Write(b)
-}
-
-func (r *responseRecorder) WriteHeader(statusCode int) {
- r.code = statusCode
-}
-
-// wrapPublicHTTPHandler augments control-plane endpoints that return
-// RouterAddresses (/info, /enroll, /enroll/status, /register) on
-// the public listener when no explicit --external-url was configured: it
-// derives the router's public ws/wss multiaddr from the incoming request's
-// Host / X-Forwarded-Host and X-Forwarded-Proto headers so single-step PaaS
-// deployments (Cloud Run, Fly.io, Render) advertise a dialable wss multiaddr
-// without a second deploy pass.
+// proxiedWithoutExternalURL counts requests that arrived through a reverse
+// proxy (X-Forwarded-Proto or X-Forwarded-Host present) while no
+// --external-url is configured. The router address and the OIDC issuer this
+// instance advertises are then its own listener, which a member behind that
+// proxy cannot reach.
+var proxiedWithoutExternalURL = promauto.NewCounter(prometheus.CounterOpts{
+ Name: "agentmesh_one_proxied_requests_without_external_url_total",
+ Help: "Requests that arrived with X-Forwarded-* headers while --external-url is not set; the advertised router address and OIDC issuer are not reachable through that proxy",
+})
+
+// wrapPublicHTTPHandler makes a misconfiguration visible: what this instance
+// advertises (the router multiaddr on /info and /enroll, the OIDC issuer in
+// discovery and in the JWTs it signs) comes from --external-url, or from its
+// own listener when the flag is absent. Nothing is derived from request
+// headers; an address a member learns is a reachability hint, and the
+// member verifies the peer's key and the router's control-plane-signed
+// credential on connection. So a hub behind a TLS-terminating proxy that
+// did not state its public URL is not unsafe, it is unreachable: the first
+// proxied request logs that, and every one is counted.
func (s *Server) wrapPublicHTTPHandler(next http.Handler) http.Handler {
+ if s.opts.ExternalURL != "" {
+ return next
+ }
+ var once sync.Once
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
- if s.opts.ExternalURL != "" || s.router == nil || !returnsRouterAddresses(r.URL.Path) {
- next.ServeHTTP(w, r)
- return
- }
- inferredAddr, ok := inferredRequestMultiaddr(r, s.PeerID())
- if !ok {
- next.ServeHTTP(w, r)
- return
+ if r.Header.Get("X-Forwarded-Proto") != "" || r.Header.Get("X-Forwarded-Host") != "" {
+ proxiedWithoutExternalURL.Inc()
+ once.Do(func() {
+ logger.Warnw("Requests arrive through a reverse proxy but --external-url is not set; the router address and the OIDC issuer this instance advertises are its own listener, which members behind the proxy cannot reach. Set --external-url to the public https URL",
+ "forwarded_proto", r.Header.Get("X-Forwarded-Proto"), "forwarded_host", r.Header.Get("X-Forwarded-Host"), "host", r.Host)
+ })
}
- rec := newResponseRecorder()
- next.ServeHTTP(rec, r)
- for k, vals := range rec.Header() {
- for _, v := range vals {
- w.Header().Add(k, v)
- }
- }
- if rec.code != http.StatusOK {
- w.WriteHeader(rec.code)
- _, _ = w.Write(rec.body.Bytes())
- return
- }
- out, ok := prependInferredRouterAddr(r.URL.Path, rec.body.Bytes(), inferredAddr)
- if !ok {
- w.WriteHeader(rec.code)
- _, _ = w.Write(rec.body.Bytes())
- return
- }
- w.Header().Set("Content-Type", "application/x-protobuf")
- w.Header().Del("Content-Length")
- w.WriteHeader(http.StatusOK)
- _, _ = w.Write(out)
+ next.ServeHTTP(w, r)
})
}
-
-func returnsRouterAddresses(path string) bool {
- switch path {
- case "/info", "/enroll", "/enroll/status", "/register":
- return true
- default:
- return false
- }
-}
-
-func prependInferredRouterAddr(path string, body []byte, inferredAddr string) ([]byte, bool) {
- prepend := func(existing []string) []string {
- out := make([]string, 0, len(existing)+1)
- out = append(out, inferredAddr)
- for _, a := range existing {
- if a != inferredAddr {
- out = append(out, a)
- }
- }
- return out
- }
- switch path {
- case "/info":
- var msg api.ControlPlaneInfoResponse
- if err := proto.Unmarshal(body, &msg); err != nil {
- return nil, false
- }
- msg.RouterAddresses = prepend(msg.RouterAddresses)
- // A member that reads /info prefers the per-router entries over the
- // flat list (candidatesFromInfo), so the entry for this router must
- // carry the inferred address too or the member dials only what the
- // router could announce itself, which behind a PaaS front end is its
- // loopback listener. Peer IDs are compared as decoded values, never
- // as strings: a peer ID has several valid string encodings.
- if info, err := peer.AddrInfoFromString(inferredAddr); err == nil {
- for _, r := range msg.Routers {
- if id, err := peer.Decode(r.GetPeerId()); err == nil && id == info.ID {
- r.Addresses = prepend(r.Addresses)
- }
- }
- }
- b, err := proto.Marshal(&msg)
- return b, err == nil
- case "/enroll", "/enroll/status":
- var msg api.BootstrapEnrollResponse
- if err := proto.Unmarshal(body, &msg); err != nil {
- return nil, false
- }
- msg.RouterAddresses = prepend(msg.RouterAddresses)
- b, err := proto.Marshal(&msg)
- return b, err == nil
- case "/register":
- var msg api.EnrollResponse
- if err := proto.Unmarshal(body, &msg); err != nil {
- return nil, false
- }
- msg.RouterAddresses = prepend(msg.RouterAddresses)
- b, err := proto.Marshal(&msg)
- return b, err == nil
- default:
- return nil, false
- }
-}
-
-// inferredRequestMultiaddr derives `/dns4/<host>/tcp/<port>/ws(s)/p2p/<peerID>`
-// from an HTTP request when the request either arrived over HTTPS (TLS or
-// X-Forwarded-Proto: https) or names a non-loopback host.
-func inferredRequestMultiaddr(r *http.Request, peerID string) (string, bool) {
- if peerID == "" {
- return "", false
- }
- host := firstForwardedValue(r.Header.Get("X-Forwarded-Host"))
- if host == "" {
- host = strings.TrimSpace(r.Host)
- }
- if host == "" {
- return "", false
- }
- scheme := "http"
- if r.TLS != nil || strings.EqualFold(firstForwardedValue(r.Header.Get("X-Forwarded-Proto")), "https") {
- scheme = "https"
- }
- if scheme == "http" && isLoopbackOrUnspecifiedHostPort(host) {
- return "", false
- }
- base, err := externalMultiaddr(scheme + "://" + host)
- if err != nil {
- return "", false
- }
- full := base + "/p2p/" + peerID
- if _, err := multiaddr.NewMultiaddr(full); err != nil {
- return "", false
- }
- return full, true
-}
-
-func firstForwardedValue(v string) string {
- if i := strings.IndexByte(v, ','); i >= 0 {
- v = v[:i]
- }
- return strings.TrimSpace(v)
-}
-
-func isLoopbackOrUnspecifiedHostPort(hostport string) bool {
- h := hostport
- if splitHost, _, err := net.SplitHostPort(hostport); err == nil {
- h = splitHost
- }
- h = strings.Trim(h, "[]")
- if strings.EqualFold(h, "localhost") || h == "" {
- return true
- }
- if ip := net.ParseIP(h); ip != nil {
- return ip.IsLoopback() || ip.IsUnspecified()
- }
- return false
-}
diff --git a/internal/standalone/standalone_test.go b/internal/standalone/standalone_test.go
index 2a551e80..028563e7 100644
--- a/internal/standalone/standalone_test.go
+++ b/internal/standalone/standalone_test.go
@@ -15,16 +15,15 @@
package standalone
import (
- "crypto/tls"
"net/http"
+ "net/http/httptest"
"os"
"path/filepath"
"testing"
- "github.com/google/agentmesh/api"
"github.com/libp2p/go-libp2p/core/crypto"
"github.com/libp2p/go-libp2p/core/peer"
- "google.golang.org/protobuf/proto"
+ dto "github.com/prometheus/client_model/go"
)
func TestWsListenMultiaddr(t *testing.T) {
@@ -137,136 +136,65 @@ func TestEnsureRouterKeyDeterministic(t *testing.T) {
}
}
-func TestInferredRequestMultiaddr(t *testing.T) {
- const testPeerID = "12D3KooWBzUDQCkZhz2rWrYBhpjcCH8VnrRNcwCW6DoF36iADYrY"
-
- reqCloudRun, _ := http.NewRequest(http.MethodGet, "http://0.0.0.0:8080/info", nil)
- reqCloudRun.Host = "agentmesh-one-xyz-uc.a.run.app"
- reqCloudRun.Header.Set("X-Forwarded-Proto", "https")
- got, ok := inferredRequestMultiaddr(reqCloudRun, testPeerID)
- want := "/dns4/agentmesh-one-xyz-uc.a.run.app/tcp/443/wss/p2p/" + testPeerID
- if !ok || got != want {
- t.Fatalf("CloudRun inferredRequestMultiaddr = (%q, %v), want (%q, true)", got, ok, want)
- }
-
- reqTLS, _ := http.NewRequest(http.MethodGet, "https://mesh.example.com:8443/info", nil)
- reqTLS.Host = "mesh.example.com:8443"
- reqTLS.TLS = &tls.ConnectionState{}
- got, ok = inferredRequestMultiaddr(reqTLS, testPeerID)
- want = "/dns4/mesh.example.com/tcp/8443/wss/p2p/" + testPeerID
- if !ok || got != want {
- t.Fatalf("TLS inferredRequestMultiaddr = (%q, %v), want (%q, true)", got, ok, want)
- }
-
- reqLoopback, _ := http.NewRequest(http.MethodGet, "http://127.0.0.1:8080/info", nil)
- reqLoopback.Host = "127.0.0.1:8080"
- if got, ok := inferredRequestMultiaddr(reqLoopback, testPeerID); ok {
- t.Fatalf("Loopback HTTP should not infer external multiaddr, got %q", got)
- }
-}
-
-func TestPrependInferredRouterAddr(t *testing.T) {
- const inferred = "/dns4/agentmesh-one-xyz.a.run.app/tcp/443/wss/p2p/12D3KooWBzUDQCkZhz2rWrYBhpjcCH8VnrRNcwCW6DoF36iADYrY"
- const local = "/ip4/127.0.0.1/tcp/8080/ws/p2p/12D3KooWBzUDQCkZhz2rWrYBhpjcCH8VnrRNcwCW6DoF36iADYrY"
-
- enrollIn, err := proto.Marshal(&api.BootstrapEnrollResponse{
- RouterAddresses: []string{local},
- })
- if err != nil {
- t.Fatalf("Marshal BootstrapEnrollResponse: %v", err)
- }
- enrollOutBytes, ok := prependInferredRouterAddr("/enroll", enrollIn, inferred)
- if !ok {
- t.Fatal("prependInferredRouterAddr(/enroll) returned false")
- }
- var enrollOut api.BootstrapEnrollResponse
- if err := proto.Unmarshal(enrollOutBytes, &enrollOut); err != nil {
- t.Fatalf("Unmarshal BootstrapEnrollResponse: %v", err)
- }
- if len(enrollOut.RouterAddresses) != 2 || enrollOut.RouterAddresses[0] != inferred || enrollOut.RouterAddresses[1] != local {
- t.Fatalf("BootstrapEnrollResponse.RouterAddresses = %v, want [%s %s]", enrollOut.RouterAddresses, inferred, local)
- }
-
- regIn, err := proto.Marshal(&api.EnrollResponse{
- BiscuitToken: []byte("tok"),
- RouterAddresses: []string{local},
+// A hub behind a reverse proxy that did not state --external-url advertises
+// its own listener, which members behind the proxy cannot reach. The first
+// proxied request says so, every proxied request is counted, and the
+// request itself is served unchanged. With --external-url, or without
+// forwarded headers, nothing is counted.
+func TestWrapPublicHTTPHandlerCountsProxiedRequestsWithoutExternalURL(t *testing.T) {
+ served := 0
+ next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ served++
+ w.WriteHeader(http.StatusNoContent)
})
- if err != nil {
- t.Fatalf("Marshal EnrollResponse: %v", err)
- }
- regOutBytes, ok := prependInferredRouterAddr("/register", regIn, inferred)
- if !ok {
- t.Fatal("prependInferredRouterAddr(/register) returned false")
- }
- var regOut api.EnrollResponse
- if err := proto.Unmarshal(regOutBytes, &regOut); err != nil {
- t.Fatalf("Unmarshal EnrollResponse: %v", err)
+ counter := func(t *testing.T) float64 {
+ t.Helper()
+ var m dto.Metric
+ if err := proxiedWithoutExternalURL.Write(&m); err != nil {
+ t.Fatal(err)
+ }
+ return m.GetCounter().GetValue()
}
- if len(regOut.RouterAddresses) != 2 || regOut.RouterAddresses[0] != inferred || regOut.RouterAddresses[1] != local {
- t.Fatalf("EnrollResponse.RouterAddresses = %v, want [%s %s]", regOut.RouterAddresses, inferred, local)
+ serve := func(h http.Handler, forwardedProto, forwardedHost string) int {
+ req := httptest.NewRequest(http.MethodGet, "http://0.0.0.0:8080/info", nil)
+ if forwardedProto != "" {
+ req.Header.Set("X-Forwarded-Proto", forwardedProto)
+ }
+ if forwardedHost != "" {
+ req.Header.Set("X-Forwarded-Host", forwardedHost)
+ }
+ rec := httptest.NewRecorder()
+ h.ServeHTTP(rec, req)
+ return rec.Code
}
- // /info carries the per-router list a member prefers; the entry for this
- // router gets the inferred address, another router's entry is untouched.
- const otherPeer = "12D3KooWDk5pWkyxVERi6kt3TyRZCaXWqg441QEQxaGkn5rWHB21"
- const otherAddr = "/dns4/router-b.example.com/tcp/443/wss/p2p/" + otherPeer
- infoIn, err := proto.Marshal(&api.ControlPlaneInfoResponse{
- RouterAddresses: []string{local},
- Routers: []*api.RouterInfo{
- {PeerId: "12D3KooWBzUDQCkZhz2rWrYBhpjcCH8VnrRNcwCW6DoF36iADYrY", Addresses: []string{local}},
- {PeerId: otherPeer, Addresses: []string{otherAddr}},
- {PeerId: "not-a-peer-id", Addresses: []string{"/ip4/10.0.0.1/tcp/1/ws"}},
- },
- })
- if err != nil {
- t.Fatalf("Marshal ControlPlaneInfoResponse: %v", err)
+ inferring := (&Server{opts: Options{}}).wrapPublicHTTPHandler(next)
+ before := counter(t)
+ if code := serve(inferring, "", ""); code != http.StatusNoContent {
+ t.Fatalf("plain request: status %d, want 204", code)
}
- infoOutBytes, ok := prependInferredRouterAddr("/info", infoIn, inferred)
- if !ok {
- t.Fatal("prependInferredRouterAddr(/info) returned false")
+ if got := counter(t); got != before {
+ t.Errorf("plain request counted: %v, want %v", got, before)
}
- var infoOut api.ControlPlaneInfoResponse
- if err := proto.Unmarshal(infoOutBytes, &infoOut); err != nil {
- t.Fatalf("Unmarshal ControlPlaneInfoResponse: %v", err)
+ if code := serve(inferring, "https", "agentmesh-one-xyz-uc.a.run.app"); code != http.StatusNoContent {
+ t.Fatalf("proxied request: status %d, want 204 (served unchanged)", code)
}
- if len(infoOut.RouterAddresses) != 2 || infoOut.RouterAddresses[0] != inferred || infoOut.RouterAddresses[1] != local {
- t.Fatalf("ControlPlaneInfoResponse.RouterAddresses = %v, want [%s %s]", infoOut.RouterAddresses, inferred, local)
+ if code := serve(inferring, "", "agentmesh-one-xyz-uc.a.run.app"); code != http.StatusNoContent {
+ t.Fatalf("proxied request (host only): status %d, want 204", code)
}
- if len(infoOut.Routers) != 3 {
- t.Fatalf("ControlPlaneInfoResponse.Routers has %d entries, want 3", len(infoOut.Routers))
+ if got := counter(t); got != before+2 {
+ t.Errorf("two proxied requests counted as %v, want %v", got-before, 2)
}
- if got := infoOut.Routers[0].Addresses; len(got) != 2 || got[0] != inferred || got[1] != local {
- t.Fatalf("Routers[0].Addresses = %v, want [%s %s]", got, inferred, local)
- }
- if got := infoOut.Routers[1].Addresses; len(got) != 1 || got[0] != otherAddr {
- t.Fatalf("Routers[1].Addresses = %v, want [%s] (another router's entry must not change)", got, otherAddr)
- }
- if got := infoOut.Routers[2].Addresses; len(got) != 1 || got[0] != "/ip4/10.0.0.1/tcp/1/ws" {
- t.Fatalf("Routers[2].Addresses = %v, want the entry with an undecodable peer id untouched", got)
- }
-
- if returnsRouterAddresses("/refresh") {
- t.Fatal("returnsRouterAddresses(/refresh) = true, want false")
- }
- if !returnsRouterAddresses("/register") {
- t.Fatal("returnsRouterAddresses(/register) = false, want true")
- }
-}
-func TestResponseRecorder(t *testing.T) {
- rec := newResponseRecorder()
- rec.Header().Set("Content-Length", "12")
- rec.WriteHeader(http.StatusCreated)
- if _, err := rec.Write([]byte("hello world!")); err != nil {
- t.Fatalf("rec.Write: %v", err)
- }
- if rec.code != http.StatusCreated {
- t.Fatalf("rec.code = %d, want %d", rec.code, http.StatusCreated)
+ explicit := (&Server{opts: Options{ExternalURL: "https://mesh.example.com"}}).wrapPublicHTTPHandler(next)
+ before = counter(t)
+ if code := serve(explicit, "https", "agentmesh-one-xyz-uc.a.run.app"); code != http.StatusNoContent {
+ t.Fatalf("with --external-url: status %d, want 204", code)
}
- if got := rec.body.String(); got != "hello world!" {
- t.Fatalf("rec.body = %q, want %q", got, "hello world!")
+ if got := counter(t); got != before {
+ t.Errorf("with --external-url a proxied request was counted: %v, want %v", got, before)
}
- if got := rec.Header().Get("Content-Length"); got != "12" {
- t.Fatalf("rec.Header(Content-Length) = %q, want 12", got)
+ if served != 4 {
+ t.Errorf("next handler served %d requests, want 4", served)
}
}
diff --git a/site/content/docs/guides/cloud-run.md b/site/content/docs/guides/cloud-run.md
index 0e950015..07c093ed 100644
--- a/site/content/docs/guides/cloud-run.md
+++ b/site/content/docs/guides/cloud-run.md
@@ -8,11 +8,13 @@ aliases:
`agentmesh-one` serves its HTTP API, the web console, and the router's WebSocket
transport on a single port (`8080`), and ships as a pre-built container image
-(`ghcr.io/google/agentmesh-one:latest`). Because `agentmesh-one` automatically infers its
-public `wss://` router address from Cloud Run's `Host` and `X-Forwarded-Proto`
-headers on `/info` and `/enroll` and derives a deterministic router `PeerID`
-from `AGENTMESH_ADMIN_TOKEN`, you can deploy a standalone control plane and router to
-Google Cloud Run in a single command.
+(`ghcr.io/google/agentmesh-one:latest`). It derives a deterministic router `PeerID`
+from `AGENTMESH_ADMIN_TOKEN`, and a Cloud Run service URL is known before the
+service exists (`https://<service>-<project number>.<region>.run.app`), so you
+can deploy a standalone control plane and router to Google Cloud Run in a
+single command. The URL goes in `--external-url`: it is the router address
+members dial and the OIDC issuer the control plane signs with, and
+`agentmesh-one` never infers either from request headers.
*(Note: For multi-cloud VM deployments on GCP, AWS, Azure, OCI, or Kubernetes,
see the [SkyPilot guide](../skypilot/).)*
@@ -24,6 +26,8 @@ PROJECT=my-gcp-project
REGION=us-central1
JOIN_TOKEN="mesh_tok_$(openssl rand -hex 16)"
ADMIN_TOKEN="mesh_adm_$(openssl rand -hex 16)"
+PROJECT_NUMBER=$(gcloud projects describe "$PROJECT" --format='value(projectNumber)')
+EXTERNAL_URL="https://agentmesh-one-${PROJECT_NUMBER}.${REGION}.run.app"
gcloud run deploy agentmesh-one \
--project "$PROJECT" --region "$REGION" \
@@ -33,9 +37,15 @@ gcloud run deploy agentmesh-one \
--port 8080 \
--no-cpu-throttling \
--timeout 3600 \
- --set-env-vars "AGENTMESH_TOKEN=${JOIN_TOKEN},AGENTMESH_ADMIN_TOKEN=${ADMIN_TOKEN}"
+ --set-env-vars "AGENTMESH_TOKEN=${JOIN_TOKEN},AGENTMESH_ADMIN_TOKEN=${ADMIN_TOKEN},AGENTMESH_EXTERNAL_URL=${EXTERNAL_URL}"
```
+Without `--external-url` (or `AGENTMESH_EXTERNAL_URL`) the instance advertises
+its own listener, which nothing outside Cloud Run can reach. The first request
+that arrives through the front door then logs
+`Requests arrive through a reverse proxy but --external-url is not set`, and
+`agentmesh_one_proxied_requests_without_external_url_total` counts them.
+
### Production persistence with PostgreSQL
By default, Cloud Run's container filesystem is in-memory. When an instance
diff --git a/site/content/docs/reference/agentmesh-one.md b/site/content/docs/reference/agentmesh-one.md
index fe80d752..69eb4c9c 100644
--- a/site/content/docs/reference/agentmesh-one.md
+++ b/site/content/docs/reference/agentmesh-one.md
@@ -29,7 +29,7 @@ downloaded tunnel connector.
|---|---|---|
| `--bind-address` | `0.0.0.0` | Host to bind. |
| `--port` | `0` | TCP port. `0` picks a free one and prints it in the banner. |
-| `--external-url` | | Public URL on which nodes reach this instance, for a reverse proxy or a hosted platform. Can also be set with `AGENTMESH_EXTERNAL_URL`. When omitted behind an HTTPS proxy (Cloud Run, Fly.io, a forwarded Codespaces port), `/info` infers the advertised `wss` address from the incoming `Host` or `X-Forwarded-Host` and `X-Forwarded-Proto` headers automatically. |
+| `--external-url` | | Public URL on which nodes reach this instance, for a reverse proxy or a hosted platform. Can also be set with `AGENTMESH_EXTERNAL_URL`. It is the router address members dial and the OIDC issuer the control plane signs with; neither is inferred from request headers. Behind a proxy (Cloud Run, Fly.io, a forwarded Codespaces port) set it, or use `--tunnel`; without it the instance advertises its own listener, logs a warning on the first proxied request and counts them in `agentmesh_one_proxied_requests_without_external_url_total`. |
| `--tunnel` | | Publish the port through a tunnel provider and use the resulting URL as the external URL. Providers: `cloudflare` (a free quick tunnel on `*.trycloudflare.com` by default, no account needed) and `codespaces` (the `https` URL GitHub Codespaces assigns to the forwarded port, read from `CODESPACE_NAME` and `GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN`; nothing is started, and the log reports whether the port answers from the internet). |
| `--tunnel-token-path` | | File containing the tunnel provider authentication token (can also be set with `AGENTMESH_TUNNEL_TOKEN`). Use together with `--tunnel <provider> --external-url https://mesh.example.com` for a permanent custom domain. |
| `--tunnel-install` | `false` | Download the pinned, digest-verified `cloudflared` into `<data-dir>/bin` without asking. Implies acceptance of its license. |