Hermex 是一个为 iPhone 设计的原生客户端，用于控制你自托管的 Hermes AI 助手。其核心理念是“手机作为控制台”，AI 的计算和你的数据都保留在你自己的服务器上，确保了隐私和安全。

📋 部署概览：你需要准备什么？

部署 Hermex 本质上不是部署手机 App 本身，而是部署并暴露一个可供 Hermex 连接的后端服务。整个过程分为两大步：

  1. 部署后端：在你的服务器（macOS/Linux/Windows WSL2）上安装并运行 hermes-webui。
  2. 连接客户端：在你的 iPhone 上安装 Hermex App，并连接到上一步设置好的服务器。

其核心架构和连接流程如下：

🖥️ 第一步：部署后端服务器 (hermes-webui)

你需要在你的服务器上运行 hermes-webui，这是 Hermex 通信的后端。

方案一：使用 Docker 部署（推荐）

这是最便捷的方式，可以避免环境依赖问题。

  1. 准备数据目录：

    1
    2
    mkdir hermes-webui && cd hermes-webui
    mkdir -p hermes_data

  2. 创建 docker-compose.yml 文件，内容如下：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    services:
      hermes-webui:
        image: ekkoye8888/hermes-webui:latest # 使用官方预构建镜像 [citation:9]
        container_name: hermes-webui
        restart: unless-stopped
        ports:
          - "8787:8787" # 将容器端口映射到宿主机 [citation:1]
        environment:
          - HERMES_WEBUI_PASSWORD=your-strong-password-here # 务必修改为强密码！
          - PORT=8787
          - BIND_HOST=0.0.0.0
        volumes:
          - ./hermes_data:/home/agent/.hermes # 持久化数据 [citation:9]

  3. 启动服务：

    1
    docker compose up -d

方案二：从源码运行

如果你更习惯直接使用 Python 环境。

  1. 克隆并安装：

    1
    2
    3
    git clone https://github.com/nesquena/hermes-webui.git
    cd hermes-webui
    pip install -r requirements.txt

  2. 设置密码并启动：

    1
    2
    export HERMES_WEBUI_PASSWORD="your-strong-password-here"
    python main.py

    服务默认会运行在 http://localhost:8787。

🌐 第二步：让服务器可从 iPhone 访问

hermes-webui 启动后，默认只能在本机访问。你需要通过以下任一方式，让你的 iPhone 能连接到它。推荐使用 HTTPS，以满足 iOS 的 App Transport Security (ATS) 要求。

  • 方案 A：Cloudflare Tunnel (推荐)：无需公网 IP 和域名，一键生成 HTTPS 地址。

    1
    2
    # 下载并运行 cloudflared
    cloudflared tunnel --url http://localhost:8787

    运行后会生成一个 https://xxxx.trycloudflare.com 的地址，在 Hermex 中输入它即可。

  • 方案 B：Tailscale：在服务器和 iPhone 上安装 Tailscale，组成一个安全的虚拟局域网。在服务器上绑定服务到 0.0.0.0，然后在 Hermex 中输入 Tailscale 分配给服务器的 IP 地址即可。

  • 方案 C：反向代理：如果你有自己的域名和 SSL 证书，可以使用 Nginx 或 Caddy 配置反向代理，将 https://your-domain.com 指向 http://localhost:8787。

📱 第三步：在 iPhone 上安装并连接 Hermex

  1. 安装 Hermex：推荐从 App Store 下载，这是最简单安全的方式。你也可以从 GitHub 克隆源码，用 Xcode 26+ 自行编译。
  2. 连接服务器：打开 Hermex App，在欢迎界面输入你的服务器地址（例如 https://xxxx.trycloudflare.com）和你在第一步中设置的 HERMES_WEBUI_PASSWORD，点击连接即可。

🔧 可选配置：启用高级功能

如果你需要使用定时任务功能，需要部署 hermes-agent 网关容器，并配置 API_SERVER_KEY。这需要编写一个更复杂的 docker-compose.yml，请参考官方多容器部署文档。

❓ 常见连接问题排查

如果连接失败，请按此顺序检查：

  1. 服务器是否开机且 hermes-webui 正在运行？
  2. 能否在服务器本地通过 curl http://localhost:8787/health 访问？（应返回健康状态）
  3. 隧道（如 Cloudflare Tunnel）或反向代理是否正常运行？
  4. iPhone 和服务器是否在同一网络或 Tailscale 网络中？
  5. HERMES_WEBUI_PASSWORD 是否输入正确？