docs(agents): explain Docker webhook networking (0.0.0.0 bind + loopback rewrite)#4721
Open
andresberrios wants to merge 1 commit into
Open
Conversation
…ack rewrite) The runtime server runs in Docker while the app runs on the host, so webhook callbacks cross the Docker host boundary. Two behaviors are load-bearing but undocumented, and both fail silently: - The app must listen on all interfaces (0.0.0.0). An app bound to loopback only (the default for some frameworks, e.g. Nuxt/Nitro) is unreachable from the container: the agent spawns but never responds, with no error surfaced. The walkthrough's @hono/node-server example happens to bind all interfaces, masking the requirement. - A serveEndpoint host of localhost/127.0.0.1/::1 is rewritten to host.docker.internal before webhook dispatch (via ELECTRIC_AGENTS_REWRITE_LOOPBACK_WEBHOOKS_TO, set by the CLI compose). This is why `agents types` shows host.docker.internal for a localhost serveEndpoint — previously unexplained and confusing. Add a warning callout to the app-setup reference and the walkthrough, covering the 0.0.0.0 requirement, the loopback rewrite, and the on-host caveat (variable unset when not running in Docker).
✅ Deploy Preview for electric-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Following the agents docs on a local Docker setup, a custom app can spawn agents but they never respond, with no error surfaced anywhere — an unusually hard failure to diagnose that can push people off the platform. The runtime server runs in a Docker container (started by the CLI) while the app runs on the host, so webhook callbacks cross the Docker host boundary. Two behaviors are load-bearing here, and neither is documented:
The app must listen on all interfaces (
0.0.0.0), not just loopback. An app bound only to127.0.0.1/localhostis unreachable from the container. Node'shttpserver and@hono/node-serverbind all interfaces by default, so the walkthrough's own example works — which quietly masks the requirement. Frameworks that default to loopback-only (e.g. Nuxt/Nitro) fail silently: the agent spawns, the webhook is never delivered, nothing is logged.Loopback
serveEndpointURLs are rewritten tohost.docker.internal.rewriteLoopbackWebhookUrl(packages/agents-server/src/utils/webhook-url.ts) rewrites aserveEndpointhost oflocalhost/127.0.0.1/::1to the Docker host before dispatching webhooks, gated byELECTRIC_AGENTS_REWRITE_LOOPBACK_WEBHOOKS_TO(set tohost.docker.internalby the CLI's docker-compose). This is whyelectric-ax agents typesprintshttp://host.docker.internal:3000/electric-agentsfor aserveEndpointconfigured ashttp://localhost:3000/...— currently unexplained, so readers can't tell how a container reaches alocalhostURL, and can't reason about running the server on the host (where the variable is unset and the rewrite correctly does not apply).Change
Docs only. Adds a
::: warningcallout to:app-setup.md(the runtime-handler reference) — after the HTTP server section.walkthrough.md— right before theagents typesoutput, so it explains thehost.docker.internalline the reader is about to see.Each callout covers the
0.0.0.0bind requirement (and its silent-failure mode), the loopback rewrite and the env var that controls it, and the on-host caveat. No code or behavior changes.