在 Windows (WSL 2) 與 Docker 生態系中部署 Hermes Agent 時，多數團隊常會遭遇兩大經典痛點

1. 網路命名空間衝突：官方預設的 network_mode: host 在 WSL 2 環境下容易導致通訊埠對應失效，使宿主機無法建立連線。

2. 跨容器通訊中斷：若將 Gateway 與 Dashboard 拆分為獨立容器，容易因為跨 Bridge 網路導致 WebSocket 路由失效，使 Dashboard 聊天介面持續顯示 reconnecting。

本文將分享如何透過 單一容器架構（Single-Container Architecture） 與 本地迴圈繫結（Localhost Loopback Binding），徹底解決上述網路與連線問題。

💡 核心修改說明

• 單一容器部屬 (Single-Container Architecture)：
    Hermes Agent 官方映像檔內建 s6-overlay 進程管理器。設定環境變數 HERMES_DASHBOARD=1 後，容器會同時啟動 Gateway 與 Dashboard 服務，避免跨容器 Bridge 網路的 WebSocket 路由問題。

• 通訊埠安全繫結 (Localhost Binding)：
    將通訊埠明確繫結至 127.0.0.1（如 127.0.0.1:9119:9119），僅允許 Windows 宿主機存取，防止同區域網路（LAN）的其他裝置存取。

🛠️ 部署與設定步驟

第一步：編寫 docker-compose.yml

在 WSL 的 /path/to/hermes-agent 目錄下建立或替換 docker-compose.yml 檔案，使用以下穩定且經過驗證的單容器整合設定：

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "127.0.0.1:8642:8642"   # Gateway API (僅限本機迴圈存取)
      - "127.0.0.1:9119:9119"   # Dashboard (僅限本機迴圈存取)
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_DASHBOARD=1      # 關鍵：同時啟動 Dashboard 與 Gateway 服務
      - HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
      - HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=your_secure_password # 請自行替換為安全密碼
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

第二步：環境初始化與權限設定

1. 執行初始化命令
   在 WSL 終端機中執行以下指令，初始化本機掛載資料夾：

docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup

2. 調整擁有者權限（選用）
   若日後查看容器日誌時發現權機存取錯誤（Permission Denied），可執行以下指令修復掛載目錄權限：

sudo chown -R 10000:10000 ~/.hermes

第三步：啟動服務

確認設定無誤後，在終端機執行以下指令清理舊容器並在背景啟動新服務：

docker compose down
docker compose up -d

🎉 驗證與成果

1. 前往 👉 http://localhost:9119
2. 在彈出的 Basic Auth 視窗中，輸入你在 docker-compose.yml 設定的帳號密碼。
3. 登入後即可順利進入 Dashboard。此時查看聊天介面，WebSocket 應會顯示連線成功，不再出現無限 reconnecting 的狀況！