docs(agents): explain Docker webhook networking (0.0.0.0 bind + loopback rewrite)

website/docs/agents/usage/app-setup.md

@@ -115,6 +115,16 @@ server.listen(PORT, async () => {
 })
 ```
 
+::: warning Local Docker networking
+
+In local development the runtime server runs in a Docker container (started by the CLI) while your app runs on the host. Two things make webhook callbacks reach your app:
+
+1. **Your app must listen on all interfaces (`0.0.0.0`), not just loopback.** The container reaches your app across the Docker host boundary, so an app bound only to `127.0.0.1`/`localhost` is unreachable — the agent spawns but never responds, and **no error is surfaced**. Node's `http` server and `@hono/node-server` listen on all interfaces by default; some frameworks default to loopback only (e.g. Nuxt/Nitro, which needs `devServer.host: '0.0.0.0'`).
+
+2. **Loopback `serveEndpoint` URLs are rewritten automatically.** A `serveEndpoint` whose host is `localhost`, `127.0.0.1`, or `::1` is rewritten by the server to the Docker host (`host.docker.internal`) before it dispatches webhooks — which is why a configured `http://localhost:3000/webhook` shows up as `http://host.docker.internal:3000/webhook` in `electric-ax agents types`. This is controlled by `ELECTRIC_AGENTS_REWRITE_LOOPBACK_WEBHOOKS_TO`, which the CLI's docker-compose sets to `host.docker.internal`. If you run the runtime server **directly on the host** (not in Docker) the variable is unset, so loopback URLs are left as-is — leave it unset in that case, or on-host loopback callbacks will break.
+
+:::
+
 ## registerTypes
 
 Registers all entity types with the Electric Agents runtime server and creates webhook subscriptions. Uses upsert semantics — re-registering an existing type updates it rather than erroring.

website/docs/agents/walkthrough.md

@@ -349,6 +349,15 @@ Then when you run the app you should see:
 INFO: [agent-runtime] Registered entity type: assistant
 ```
 
+::: warning How the container reaches your app
+
+The runtime server runs in Docker while your app runs on the host, so webhook callbacks cross the Docker host boundary. Two things make this work — and both are easy to trip over:
+
+- **Your app must listen on all interfaces (`0.0.0.0`), not just loopback.** The `@hono/node-server` `serve()` above already does this, so the walkthrough works as-is. But if you wire the runtime handler into a framework that binds to loopback only by default (e.g. Nuxt/Nitro), the container can't reach it — the agent spawns but never responds, with **no error**. Configure the framework to listen on `0.0.0.0` (for Nuxt: `devServer.host: '0.0.0.0'`).
+- **`localhost` in `serveEndpoint` is rewritten to `host.docker.internal` automatically.** That is why the `agents types` output below shows `http://host.docker.internal:3000/electric-agents` even though we configured `http://localhost:3000`. The rewrite is controlled by the `ELECTRIC_AGENTS_REWRITE_LOOPBACK_WEBHOOKS_TO` env var, which the CLI's docker-compose sets. If you run the runtime server directly on the host instead of in Docker, it is unset and loopback URLs are used as-is.
+
+:::
+
 Check the registered entities types on the command line:
 
 ```sh