fix: use 127.0.0.1 as default hostname for HTTP server

[Avital Ben-Natan (dewdad)]

Summary

• Fix Bun.serve() failing on Windows compiled binaries when binding to 0.0.0.0
• Default HTTP server hostname changed from 0.0.0.0 to 127.0.0.1
• Preserve 0.0.0.0 binding when --allow-remote-in-mcp is explicitly enabled
• Align assertPortAvailable probe hostname with actual Bun.serve() hostname

Problem

On Windows, browseros_server.exe (Bun compiled binary) crash-loops with:

Failed to start HTTP server (port: 9200, error: "Failed to start server. Is port 1455 in use?")

The error repeats indefinitely (5,300+ crash-restart cycles observed in logs). The "port 1455" is actually a Windows socket error code leaking into Bun's error message — the port itself is not in use.

Root cause: Bun.serve({ hostname: '0.0.0.0' }) fails in compiled binaries on Windows. The assertPortAvailable probe succeeds because it binds to 127.0.0.1, but then Bun.serve() attempts 0.0.0.0 which triggers the failure.

Related: oven-sh/bun#12127

Fix

1. server.ts: Default host changed from '0.0.0.0' to '127.0.0.1'
2. server.ts: assertPortAvailable() now accepts and uses the same host parameter as Bun.serve() (was hardcoded to '127.0.0.1')
3. main.ts: Host selection respects --allow-remote-in-mcp flag: this.config.mcpAllowRemote ? '0.0.0.0' : '127.0.0.1'

This is also a security improvement — the MCP server only needs localhost connections by default, so binding to 0.0.0.0 was unnecessarily broad.

Testing

• Verified on Windows 11 with BrowserOS v0.44.0.1 (Chromium 146.0.7821.31)
• The server previously crashed immediately on every startup; with 127.0.0.1 it should bind successfully

Fixes #498

[github-actions]

Thank you for your contribution! Before we can merge this PR, we need you to sign our Contributor License Agreement.

To sign the CLA, please add a comment to this PR with the following text:

I have read the CLA Document and I hereby sign the CLA

You only need to sign once. After signing, this check will pass automatically.

---

Troubleshooting

• Already signed but still failing? Comment recheck to trigger a re-verification.
• Signed with a different email? Make sure your commit email matches your GitHub account email, or add your commit email to your GitHub account.

- - - I have read the CLA Document and I hereby sign the CLA - - - _{You can retrigger this bot by commenting **recheck** in this Pull Request. Posted by the **CLA Assistant Lite bot**.}

[greptile-apps]

Greptile Summary

This PR fixes a Windows-specific crash loop in browseros_server.exe (Bun compiled binary) where Bun.serve({ hostname: '0.0.0.0' }) fails with a misleading Windows socket error code. The fix changes the default binding address to 127.0.0.1 and gates 0.0.0.0 behind the explicit --allow-remote-in-mcp flag, while also aligning the assertPortAvailable probe host with the actual Bun.serve() hostname to eliminate the pre-existing inconsistency that masked the root cause.

• server.ts: Default host changed from '0.0.0.0' to '127.0.0.1'; assertPortAvailable now accepts host as a parameter and passes it to the TCP probe — ensuring the availability check and the actual server bind to the same address
• main.ts: Host selection uses this.config.mcpAllowRemote ? '0.0.0.0' : '127.0.0.1', correctly preserving remote-access capability for users who opt in
• Security improvement: Binding to loopback by default reduces unnecessary network exposure
• Minor: Startup log messages in main.ts still hardcode 127.0.0.1 even when mcpAllowRemote is true, which could be misleading for operators using the remote-access mode

Confidence Score: 5/5

Safe to merge — the fix is targeted, correct, and a security improvement; only a minor log message accuracy issue remains.

All remaining findings are P2 style suggestions. The core logic — aligning assertPortAvailable and Bun.serve() to the same host and defaulting to 127.0.0.1 — is correct and directly addresses the reported Windows crash. No regressions are introduced; 0.0.0.0 is still reachable via the --allow-remote-in-mcp flag.

No files require special attention.

Important Files Changed

Filename	Overview
apps/server/src/api/server.ts	Default hostname changed from 0.0.0.0 to 127.0.0.1; assertPortAvailable now accepts and forwards the host parameter so the probe and Bun.serve() bind to the same address — eliminating the root-cause mismatch on Windows.
apps/server/src/main.ts	Host selection now respects --allow-remote-in-mcp flag (0.0.0.0 when set, 127.0.0.1 otherwise). Minor style issue: startup log messages still hardcode 127.0.0.1 even when the server binds to 0.0.0.0.

Sequence Diagram

sequenceDiagram
    participant Main as main.ts (Application.start)
    participant Server as server.ts (createHttpServer)
    participant Probe as assertPortAvailable (node:net)
    participant Bun as Bun.serve()

    Main->>Main: mcpAllowRemote ? '0.0.0.0' : '127.0.0.1'
    Main->>Server: createHttpServer({ port, host })
    Server->>Probe: assertPortAvailable(port, host)
    Note over Probe: probe.listen({ port, host, exclusive: true })<br/>host is now the SAME as Bun.serve() will use
    Probe-->>Server: resolve (port is free)
    Server->>Bun: Bun.serve({ port, hostname: host })
    Note over Bun: Previously: assertPortAvailable used '127.0.0.1'<br/>but Bun.serve used '0.0.0.0' → Windows crash
    Bun-->>Server: server instance
    Server-->>Main: { app, server, config }

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: apps/server/src/main.ts
Line: 106-111

Comment:
**Log messages hardcode `127.0.0.1` when binding to `0.0.0.0`**

When `--allow-remote-in-mcp` is enabled the server binds to `0.0.0.0`, but the startup log messages still unconditionally print `127.0.0.1`. This can mislead operators who need to know the actual bound address for remote-access scenarios.

```suggestion
    const boundHost = this.config.mcpAllowRemote ? '0.0.0.0' : '127.0.0.1'
    logger.info(
      `HTTP server listening on http://${boundHost}:${this.config.serverPort}`,
    )
    logger.info(
      `Health endpoint: http://${boundHost}:${this.config.serverPort}/health`,
    )
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "fix: use 127.0.0.1 as default hostname f..." | Re-trigger Greptile}