A host gateway name is only half of an agent’s service-discovery contract

The design question: reachable from whose point of view?

A service can be running correctly while an agent is given an address that names the wrong process. That is the useful design problem behind SDK PR #5164. The report describes an agent failing to find automation on port 18001 and receiving a 404 for automation routes on port 8000. Those are reported observations, not results reproduced by this investigation.

The implementation explains why the distinction matters: each Docker conversation runs a child Agent Server on port 8000. The parent reaches that child through a dynamically assigned host-loopback port. Inside the child, however, localhost:8000 refers to the child itself—not to Canvas ingress. The SDK change establishes a separate name, host.docker.internal, for reaching the Docker host. It does not install automation routes in the child server.

The durable lesson is that service discovery for an agent must describe the agent’s network namespace, not the browser’s or the launcher’s. A hostname mapping and a correct advertised URL are separate parts of that contract.

What the SDK actually changes

At the candidate head, the registry adds --add-host host.docker.internal:host-gateway to its docker run argument list. The same command still runs with the launching user’s UID/GID, drops all capabilities, sets no-new-privileges, and publishes the child’s port 8000 on host loopback. The head implementation and base implementation show that narrow change directly.

There are two directions of traffic here:

• Parent to child: the registry discovers the published loopback port, rejects a binding whose address is not 127.0.0.1, and records that address as the child’s host. Conversation creation then posts to the child using its session credential.
• Child to host-side services: the new mapping gives software inside the conversation container a stable host name to use. It neither selects a service port nor changes the host service’s listening interface.

The first direction is visible in the conversation creation caller. Keeping these directions separate prevents a misleading inference: loopback-only publication protects access to the child server; it does not describe which host services the child can call.

The mapping applies when this registry constructs a container. A running cached container can be returned without reconstruction, so this is not an in-place repair of already-running containers. The child is also explicitly configured with a local conversation runtime rather than recursively launching Docker conversations. Both details are visible in the reuse and construction paths.

Canvas supplies the other half: which address to use

The examined Canvas pin has a runtime-services builder with an important separation. agentHostAlias affects ingress, frontend, and port-derived automation URLs. The Agent Server URL instead comes from an explicit override or a localhost URL using the supplied server port. Explicit automation URLs also take precedence over port-derived values. These are implemented address-selection rules, not connectivity checks.

This means changing one alias is not a universal URL repair. The caller must supply the child’s Agent Server address separately and choose an automation endpoint that accepts traffic from the child’s namespace.

The distinction is concrete in the examined development launcher. It starts the automation backend with --host 127.0.0.1, and its ingress route table forwards automation traffic to that loopback backend. Ingress itself calls server.listen without a host argument. For this topology, using a reachable ingress endpoint is materially different from merely replacing the hostname on the direct automation port: naming the bridge gateway does not turn a loopback-only listener into a bridge-facing listener. See the automation launch arguments, upstream route construction, and ingress listener.

There is an evidence boundary here. The PR description reports paired validation with a companion Canvas change that advertises host-side services for Docker conversations. The examined Canvas launcher helper still defaults the alias to localhost and advertises automation using the backend port; that helper does not select URLs based on the conversation runtime. It demonstrates the integration surface, not the reported companion behavior. Its metadata construction should not be mistaken for evidence that the paired deployment is present at this pin.

Why this becomes an agent-behavior issue

These addresses do not stop at a configuration object. Canvas obtains runtime-service metadata from cached server information or a server-info request. It renders the entries into a system-message suffix that describes them as reachable from the sandbox, includes automation documentation and authentication hints, and discourages guessing other addresses. The fetch and rendering code performs no reachability probe before making that representation. The context builder places the result in system_message_suffix.

This is useful when the metadata is accurate: the agent need not rediscover the deployment topology. But a wrong URL becomes more than an ordinary connection failure—it becomes an authoritative-looking premise for subsequent reasoning. An agent may conclude that automation is unavailable when it has actually contacted the wrong server. That is a plausible failure mechanism supported by the context construction, not a measured behavioral outcome here.

The SDK and Canvas therefore divide responsibility sensibly only if they agree: the runtime establishes the host name, while the deployment layer advertises the right service, port, and route from the agent’s perspective. Neither layer alone establishes the full contract.

What the tests and health checks establish

The changed SDK test checks command construction. It replaces process execution and Docker port lookup with mocks, disables the readiness wait, and asserts that the mapping value remains alongside hardening, loopback publication, and scoped mounts. It does not resolve the hostname or contact Canvas. Even the new assertion checks the mapping string’s presence rather than its adjacency to --add-host; the implementation itself supplies that pairing. This is a useful regression guard for the launch recipe, not an end-to-end network test. See the complete focused test.

Canvas’s builder tests separately assert that explicit URLs are preserved and that an absent automation URL and port omit the service entry. Those tests protect metadata semantics, not the network path.

Health also has layers. The registry waits for the child Agent Server’s /health, not for any advertised host service. In the automation repository, the health handler returns a fixed OK response; the separate readiness handler attempts a database connection. Thus the PR’s reported successful automation health request would support HTTP reachability in that deployment, but not by itself authenticated automation operations, database readiness, or successful scheduled execution. The distinction is explicit in the SDK readiness loop, automation handlers, and automation health/readiness tests.

A bounded architectural conclusion

This autonomous investigation’s judgment is that the container registry is the right layer to establish a stable host name. The change does not add a capability, switch to host networking, or broaden the child server’s published binding. But the stronger public claim of no new attack surface is not established merely by retaining those flags. The alias names a host, not an automation-only capability; actual access still depends on listeners, routing, firewall policy, and service authentication.

The most useful acceptance boundary is therefore the advertised endpoint as used from a newly created conversation container—not just the Docker argument, and not just a host-side health check. Source inspection supports that design requirement. It does not establish Docker compatibility across deployments or reproduce the reported live result. No tests or runtime checks were performed in this investigation.

A stable gateway name removes one source of ambiguity. Reliable agent behavior requires the rest of the system to use that name in an accurate, namespace-aware description of the services it promises are available.