Hermex: a native iPhone client for your self-hosted Hermes agent

What Hermex solves, and who it is actually for

A self-hosted agent is pleasant on a desktop and awkward everywhere else. The process runs on a machine you own, the web UI lives behind a tunnel, and checking on a running task means opening a laptop. Hermex closes that gap with a native SwiftUI app for iOS 18 and later, built as a mobile cockpit for a hermes-webui server. The README frames the split directly: the phone is the control plane, not the compute plane. The agent, its tools and your data stay on your hardware.

The audience is narrow and specific. You need to be running hermes-webui already, on macOS, Linux or Windows through WSL2, with Python 3.11 or newer. If you have never installed that server, Hermex has nothing to connect to, because it does not ship, host or provision a backend. The app is free, with no subscriptions and no in-app purchases, and the README claims no analytics, no tracking and no third-party relay. That claim matters for the audience it targets: people who moved their agent off hosted infrastructure precisely so a middleman would not see the traffic.

What you get once connected is a set of panels rather than a chat box alone. Chat with model, reasoning-effort, workspace and profile options, file and image attachments, streamed responses with thinking and tool-call detail, the ability to steer or stop a run mid-flight. Sessions are browsable, searchable and resumable, and cached sessions stay readable offline. Tasks exposes the agent's scheduled cron jobs for viewing and editing. Skills is searchable. There is a workspace file browser, plus read-only Memory and Insights panels. Read-only is the honest word for those two: you inspect agent memory and usage analytics, you do not edit them from the phone.

How the app talks to your server

The architecture is a direct client-server relationship with no intermediary hop. Hermex holds a server URL and a password, and it speaks to whatever hermes-webui exposes at that address. The README does not publish the endpoint list, so the exact request shapes are not something I can describe from the repository alone. What is documented is the health endpoint, which is the same one the troubleshooting steps tell you to curl from a terminal.

That single endpoint is the most useful thing to understand about the design. Because the app has no relay, reachability is entirely your problem, and the README says so: self-hosting the server, securing it and keeping it reachable are your responsibility. The consequence is that every failure mode is a networking failure mode. The troubleshooting list reads like a checklist for that reality. Is the host machine awake. Is hermes-webui running and serving /health. Is the tunnel, reverse proxy or Tailscale route connected. Are the URL and password correct.

Transport choice is where the design gets opinionated. The recommended path is HTTPS through a tunnel or reverse proxy that terminates real TLS at a hostname you own, because that keeps iOS App Transport Security satisfied with no exceptions. Tailscale Serve is offered as the private alternative, with the server password-protected and bound to 127.0.0.1:8787. Plain HTTP bound directly to 0.0.0.0 is described as a manual fallback, not the default, and the README is blunt that on a publicly reachable hostname the password is your only app-level defense. That is a fair warning, not a marketing line.

Installing Hermex and connecting it to a server

The intended install is the App Store build, and the README says to prefer it unless you are developing. Setup is described as roughly 15 minutes across three steps: run the server, make it reachable from your phone, then connect.

Start the server side first. The README names the environment variable that gates access, and it should be set to something strong, since on a public hostname it is the only app-level defense.

HERMES_WEBUI_PASSWORD

Before touching the phone, confirm the server answers. The README's troubleshooting section uses this exact check, and it is the fastest way to separate a server problem from a phone problem.

curl https://<your-server>/health

If you would rather keep the server off the public internet, the README's private path is Tailscale Serve, with the server bound to 127.0.0.1:8787. Inspect existing routes first, then add the serve rule only when HTTPS port 443 at the root path is free.

tailscale serve status
tailscale serve --bg 8787

Then install Hermex on the iPhone, enter the server URL and password, and connect. The README's example URL is a hostname form, https://hermes.yourdomain.com, and for Tailscale it says to use the exact https://...ts.net URL that tailscale serve status reports. Simulator-only local testing can use http://localhost:8787 when the server runs on the same Mac. If connection testing fails, work the four checks in order rather than reinstalling the app.

Building from source is a different exercise. It needs Xcode 26 or newer with the iOS 18 SDK, a device or simulator on iOS 18+, and the repository's HermesMobile.xcodeproj. The Xcode target is HermesMobile even though the app displays as Hermex, which is worth knowing before you go looking for a target with the app's name.

xcodebuild -project HermesMobile.xcodeproj -scheme HermesMobile -destination 'platform=iOS Simulator,name=iPhone 17' build

If that simulator is not installed, list what is available and pick a nearby iPhone model.

xcrun simctl list devices available

Version skew is the real limitation

The app is developed and tested against a specific hermes-webui commit, pinned in the file UPSTREAM_TESTED_SHA. The repository also carries HERMES_AGENT_TESTED_SHA. Two pinned SHAs, one for the web UI and one for the agent, tell you how the maintainer thinks about compatibility: as a tested point, not a range.

That is not paranoia. The README states that upstream does not yet guarantee API stability, and that its own README declares version skew unsupported pending stable-API work. So newer or older server versions may break individual features. Read the practical consequence carefully. Hermex is not a client you can point at any hermes-webui build and trust. If you update the server past the tested commit, you are running ahead of the app's validation, and a feature that worked yesterday may not work today. If you run an older server, the same applies in reverse.

This shapes who should adopt it. Someone who keeps a server on a pinned commit and updates deliberately will be fine. Someone who tracks upstream's main branch and expects the phone to keep up automatically is signing up for exactly the breakage the README warns about. The repository does ship a CHANGELOG.md, and releases are frequent, with v1.6.0 on 2026-09-06, v1.5.0 on 2026-08-04 and v1.4.0 on 2026-07-13, so the client side moves. The server side is the variable you control.

There is a second boundary worth naming: platform. This is an iPhone app for iOS 18 and later. The topics list includes iOS and SwiftUI, and the README describes a native app, not a web wrapper. Android is not part of this project. If your team is split across platforms, Hermex covers one half of it.

How Hermex differs from reaching the web UI in a browser

The obvious alternative is the hermes-webui interface itself, opened in mobile Safari against the same server. The difference is not cosmetic. A browser gives you the full web UI, including whatever administrative surface it exposes, and it works on any device with a browser, including Android. Hermex trades that breadth for a native surface: streamed responses with thinking and tool-call detail, the ability to steer or stop a run mid-flight, cached sessions that stay readable offline, and dedicated screens for Tasks, Skills, Memory and Insights rather than pages you navigate to.

Offline reading is the sharpest split. The README says cached sessions stay readable offline, which a browser tab pointed at a tunnel will not give you once the connection drops. If you read past conversations on a train, that difference is the whole argument.

The trade runs the other way on coverage. The web UI is the reference implementation; Hermex is a client built against a pinned commit of it. Anything the web UI adds after that commit is, by the project's own compatibility statement, unvalidated on the phone. A browser also needs no install and no update cycle. If your use of the agent is occasional and always at a desk, the browser is simpler and there is no reason to add an app.

A second alternative is building your own thin client against the server API. The repository is MIT-licensed Swift, so that is permitted, and the app's own structure is a reference for what such a client needs. The cost is that you inherit the same version-skew problem without the tested-SHA discipline the maintainer keeps, and you maintain it yourself.

Maintenance cost, licence and what to check before upgrading

The repository is MIT-licensed, which is permissive and places few obligations on what you do with the source. The README separately credits hermes-webui as a third-party MIT-licensed project, so the two halves of the stack carry the same licence family. Nothing here is legal advice, and if you redistribute a build, read the LICENSE file rather than this paragraph.

On maintenance, the last push to the repository was on 2026-09-10, and the most recent release, v1.6.0, is dated 2026-09-06, so the client is being worked on. That says nothing about whether your server will stay compatible, because the compatibility contract is a pinned SHA, not a version range. Upgrading Hermex and upgrading hermes-webui are two separate decisions, and only the first one is inside the app's control.

The upgrade procedure the repository supports is in the tree: CHANGELOG.md for what changed, DEVELOPMENT.md for the standard post-change flow, and the two SHA files for the tested baseline. If you build from source, the test command is the one to run after pulling, and the README gives it with the same simulator destination as the build.

xcodebuild test -project HermesMobile.xcodeproj -scheme HermesMobile -destination 'platform=iOS Simulator,name=iPhone 17'

A reasonable discipline is to note your server's commit, compare it against UPSTREAM_TESTED_SHA after an app update, and treat a mismatch as a reason to check the specific features you rely on rather than as a reason to panic. The README does not document a rollback path for the server, and it does not promise that a mismatched pair degrades gracefully. That silence is the thing to plan around.

Editorial conclusion

Adopt Hermex if you already run hermes-webui on hardware you control and you want to read sessions, edit cron tasks and steer runs from an iPhone instead of a laptop browser. Do not adopt it if you have no server, if you need an Android client, or if you expect the app to host or provision the agent for you: the README states plainly that Hermex is a client only. Before installing, verify three things: that the machine hosting hermes-webui is awake and serving /health, that the server is reachable over real HTTPS through a tunnel, reverse proxy or Tailscale Serve, and that its commit matches the SHA recorded in UPSTREAM_TESTED_SHA, because the upstream README declares version skew unsupported.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. uzairansaruzi/hermex on GitHub