Windows Docker Networking Issues - network_mode:host and Hard-coded localhost URLs

[mohd-talib0]

---

name: 🐞 Bug Report
about: Report a reproducible bug or unexpected behavior
title: 'Windows Docker Networking Issues - network_mode:host and Hard-coded localhost URLs'
labels: bug, docker, windows, networking, cross-platform

Description of the issue:

The CortexON project fails to run on Windows due to two related Docker networking issues that prevent inter-service communication:

1. network_mode: host incompatibility: The docker-compose.yaml uses network_mode: host, which is not supported on Windows Docker Desktop. This prevents services from being accessible on localhost from the Windows host machine.

2. Hard-coded localhost URLs: After fixing the network mode, inter-container communication fails because cortex_on/agents/web_surfer.py and cortex_on/agents/orchestrator_agent.py use hard-coded http://localhost:8000 URLs to communicate with the agentic_browser service. In Docker bridge networking, containers must use service names (e.g., http://agentic_browser:8000) instead of localhost.

These issues prevent the web surfer agent from functioning, causing all web surfing tasks to fail with connection errors.

Steps to reproduce:

1. Clone the repository on a Windows machine with Docker Desktop installed
2. Run docker-compose up --build to start all services
3. Attempt to access the frontend at http://localhost:3000 (fails with network_mode: host)
4. Fix docker-compose.yaml by replacing network_mode: host with explicit port mappings
5. Restart services with docker-compose down && docker-compose up -d
6. Access frontend at http://localhost:3000 (now works)
7. Submit a task requiring the web surfer agent: "Check today's gold prices in Mumbai from Goodreturns.in"
8. Observe error logs showing connection failure to localhost:8000

Expected behavior:

• All services should be accessible on localhost with their respective ports (frontend: 3000, agentic_browser: 8000, cortex_on: 8081)
• The cortex_on service should successfully communicate with the agentic_browser service using Docker service names
• Web surfer tasks should execute without connection errors
• The system should work identically on Windows, Linux, and macOS

Actual behavior:

Stage 1 - With network_mode: host:

• Services start but are NOT accessible on localhost from Windows host
• Frontend only accessible via Docker internal IPs (e.g., http://192.168.65.6:3000/)
• http://localhost:3000 returns ERR_CONNECTION_REFUSED

Stage 2 - After fixing network mode to use port mappings:

• Services become accessible on localhost ✅
• Inter-container communication fails with:

  Error making API call: Cannot connect to host localhost:8000 ssl:default [Connect call failed ('127.0.0.1', 8000)]
  Failed to generate web surfer reply: Cannot connect to host localhost:8000
  

• All web surfer agent tasks fail immediately
• Gold price analysis task cannot retrieve data from Goodreturns.in

Screenshots/Logs [Mandatory]:

Error Logs from cortex_on Service:

cortex_on | 15:01:25.403     Assigning web surfing task: Navigate to Goodreturns.in and collect today's gold prices...
cortex_on | Error making API call: Cannot connect to host localhost:8000 ssl:default [Connect call failed ('127.0.0.1', 8000)]
cortex_on | Failed to generate web surfer reply: Cannot connect to host localhost:8000 ssl:default [Connect call failed ('127.0.0.1', 8000)]
cortex_on | 15:01:25.420   preparing model and tools run_step=3

Affected Code Files:

1. docker-compose.yaml (Lines 6, 15, 24):

   services:
     cortex_on:
       network_mode: host  # ❌ Not supported on Windows
     
     agentic_browser:
       network_mode: host  # ❌ Not supported on Windows
     
     frontend:
       network_mode: host  # ❌ Not supported on Windows

2. cortex_on/agents/web_surfer.py (Line 32):

   class WebSurfer:
       def __init__(self, api_url: str = "http://localhost:8000/api/v1/web/stream"):  # ❌
           self.api_url = api_url

3. cortex_on/agents/orchestrator_agent.py (Line 311):

   @orchestrator_agent.tool
   async def web_surfer_task(ctx: RunContext[orchestrator_deps], task: str) -> str:
       # ...
       web_surfer_agent = WebSurfer(api_url="http://localhost:8000/api/v1/web/stream")  # ❌

Environment (OS, Browser):

• Operating System: Windows 11
• Docker Desktop: Version 28.5.2
• Docker Compose: v2.40.3-desktop.1
• Python: 3.10 (in containers)
• Browser: Chrome/Edge (for frontend access)
• Affected Services: cortex_on, agentic_browser

---

Root Cause

Issue 1: Windows Docker Desktop does not fully support network_mode: host. This mode only works properly on Linux. On Windows, it does not expose container ports to the host machine.

Reference: Docker Documentation - Host Network Driver

Issue 2: When containers run on a Docker bridge network (the fix for Issue 1), localhost inside a container refers to that container itself, not to other containers. Docker service names must be used for inter-container communication.

---

Proposed Solution

Fix 1: Update docker-compose.yaml

Replace network_mode: host with explicit port mappings:

services:
  cortex_on:
    ports:
      - "8081:8081"
    # Remove network_mode: host

  agentic_browser:
    ports:
      - "8000:8000"
    # Remove network_mode: host

  frontend:
    ports:
      - "3000:3000"
    # Remove network_mode: host

Fix 2: Update cortex_on/agents/web_surfer.py (Line 32)

class WebSurfer:
    def __init__(self, api_url: str = "http://agentic_browser:8000/api/v1/web/stream"):  # ✅
        self.api_url = api_url

Fix 3: Update cortex_on/agents/orchestrator_agent.py (Line 311)

@orchestrator_agent.tool
async def web_surfer_task(ctx: RunContext[orchestrator_deps], task: str) -> str:
    # ...
    web_surfer_agent = WebSurfer(api_url="http://agentic_browser:8000/api/v1/web/stream")  # ✅
    # OR simply: web_surfer_agent = WebSurfer()  # Uses corrected default

---

Verification

After applying all three fixes:

1. Stop containers: docker-compose down
2. Start services: docker-compose up -d
3. Verify accessibility:
   • Frontend: http://localhost:3000 ✅
   • CortexON API: http://localhost:8081/docs ✅
   • TA-Browser API: http://localhost:8000/docs ✅
4. Submit a web surfer task and confirm successful execution
5. No "Cannot connect to host localhost:8000" errors in logs

---

Priority

HIGH - Completely blocks Windows users from running the project

[mohd-talib0]

Solution Approach

The fixes proposed above provide an immediate solution to unblock Windows users, but this is part of a broader configuration management issue.

Short-term Fix (This Issue)

Change hard-coded localhost:8000 → agentic_browser:8000 in:

• cortex_on/agents/web_surfer.py:32
• cortex_on/agents/orchestrator_agent.py:311
• docker-compose.yaml (replace network_mode: host with port mappings)

Pros: Quick fix, unblocks Windows users immediately
Cons: Still hard-coded values, not environment-configurable

---

Long-term Fix (Recommended Follow-up)

The codebase has broader configuration issues that should be addressed:

1. Infinite timeout: TIMEOUT = 9999999999... in web_surfer.py (security risk)
2. Hard-coded URLs: Service endpoints scattered across multiple files
3. No environment-based config: Can't deploy to staging/prod without code changes

Recommended solution: Environment-variable based configuration

# .env
TA_BROWSER_URL=http://agentic_browser:8000
WEB_SURFER_TIMEOUT_SECONDS=300

This would:

✅ Support dev/staging/prod environments
✅ Work with Docker Compose, Kubernetes, bare metal
✅ Fix the infinite timeout issue
✅ Provide type safety with Pydantic validation
I'll create a separate issue for the broader configuration management improvements.