Local MCP boundary
Check where your coding agent actually runs.
Hronaut binds its MCP server to host loopback. Before editing a client configuration, confirm that the client process sees the same loopback interface as the Hronaut desktop process.
The rule
127.0.0.1 belongs to the client process's network namespace.
“Running on my computer” is not enough. WSL, Docker or Podman, a Dev Container, a VM, Remote SSH, and a hosted agent may each have a different loopback interface.
Support matrix
Identify the client runtime before changing anything.
Only the native same-host path is release-tested. Hronaut does not bind to a LAN or public interface, and the safe fallback for every separate namespace is to run the coding-agent client natively on the computer running Hronaut.
| Client runtime | What 127.0.0.1 means | Support | Safe next action |
|---|---|---|---|
| Native Windows, macOS, or Linux process | The same host loopback used by Hronaut. | Supported and release-tested | Use the current endpoint and generated setup from Hronaut Home, then run the preflight below. |
| WSL | The Linux environment's loopback; forwarding behavior varies by WSL and Windows networking mode. | Unsupported / experimental | Run the coding-agent client natively on Windows. Do not assume a machine-specific forwarding rule is a Hronaut guarantee. |
| Docker, Podman, or Dev Container | The container's own loopback, not the desktop host. | Unsupported / experimental | Run the coding-agent client natively on the Hronaut host. |
| Local virtual machine | The guest operating system's loopback. | Unsupported | Run the client in the host OS alongside Hronaut. |
| Remote SSH | The remote machine's loopback. | Unsupported | Use a local client process on the Hronaut host instead of changing the listener. |
| Hosted or cloud agent | The provider's remote runtime, never your desktop loopback. | Unsupported by design | Use the agent's native local mode, if it has one, on the Hronaut host. |
Release-tested path
Verify health → MCP discovery → one harmless browser read.
Run every check from the actual environment that launches the coding agent. Copy the current endpoint and client-specific setup from Hronaut Home; replace /mcp with /healthz only for the first check.
- 1
Check listener reachability
With Hronaut open, run one copy-safe status-only probe in the client's shell.
macOS or Linux
curl --silent --show-error --output /dev/null --write-out "%{http_code}\n" http://127.0.0.1:47812/healthzWindows PowerShell
curl.exe --silent --show-error --output NUL --write-out "%{http_code}`n" http://127.0.0.1:47812/healthz200means the endpoint is reachable and this profile accepts the request.401means the endpoint is reachable but authentication is required. A refusal or timeout means no listener is reachable from this runtime. - 2
Initialize MCP and list tools
Install the exact client configuration copied from Hronaut Home, restart or refresh the client, and use its MCP status or tool-list command. Confirm that Hronaut initializes and advertises tools including
browser_statusandbrowser_snapshot. The MCP Inspector guide provides an independent same-runtime discovery path. - 3
Read synthetic public content
Ask the connected client: “Create a Hronaut workspace named topology-check, open https://example.com inside it, take a semantic snapshot, and report the page heading. Start with clean scratch storage.” A visible isolated workspace and the heading Example Domain prove usable browser state without touching a private page.
When authentication is enabled, use Hronaut Home's generated token-file or environment-placeholder setup. Never paste the bearer token or token-file contents into a command transcript, issue, chat, screenshot, or public diagnostic.
Copy-safe diagnosis
Report the failed boundary, not private data.
These reason names are safe to share. They identify the stage that failed without including tokens, private paths, account identifiers, cookies, private URLs, page content, or customer information.
| Reason | Meaning | Next check |
|---|---|---|
app_not_running | Hronaut Home is not open or its local listener has not started. | Start Hronaut and confirm Home says the MCP server is online. |
endpoint_unreachable_from_client_namespace | Home says the listener is online, but the status-only health probe cannot reach it from the client runtime. | Recheck the topology table and move the client to the Hronaut host OS. |
authentication_required | The health probe returns 401, or MCP rejects a configuration without the current credential. | Copy the generated protected-profile setup from Hronaut Home. Do not reveal the token. |
mcp_handshake_failed | Health succeeds, but MCP initialization or tool discovery does not. | Check client transport, endpoint, authentication placeholder, and client logs; then use MCP Inspector from the same runtime. |
browser_not_ready | MCP tools are visible, but the isolated public-page read cannot complete. | Open Hronaut Home, review the copy-safe MCP readiness panel, and retry browser_status or browser_snapshot in the task-owned workspace. |
Security boundary
Do not solve reachability by exposing browser control.
Hronaut intentionally listens on loopback. Do not change it to a LAN or public bind, add an unauthenticated proxy, or publish the endpoint through a tunnel. Those workarounds expand browser-control authority beyond the tested local boundary.
Platform-specific forwarding paths remain unsupported until Hronaut deliberately tests and documents them. The supported recovery is a native client process on the same host.
Next step
Now configure the client, without moving the boundary.
Once the native same-host preflight works, use the focused guide for your client and keep Hronaut Home open while you verify the connection.