Model or dataset
uzairansaruzi/hermex avatar
uzairansaruzi/hermex

Hermex is a cockpit, and the agent it drives belongs to another project

Native iPhone app for your Hermes agent

1,692 stars272 forksSwiftMIT

At a glance

What is it?
The iPhone app is a SwiftUI control plane for a self-hosted hermes-webui server that someone else maintains. Its compatibility story rests on two pinned commits and a hard floor at Hermes 0.21.3.
Who is it for?
Hermex is worth a look if you already run hermes-webui and want phone access to sessions, cron jobs, skills and the server filesystem, and if you are the kind of person who reads a pinned commit SHA before updating. It is not a product you can adopt on its own: the app ships no backend, so a fresh install has nothing to connect to until you stand up a third-party server, expose it, and protect it.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly Swift, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • uzairansaruzi/hermex1,692 ★ · +414
Star history
Repository2026-09-102026-11-13
uzairansaruzi/hermex1.3k1.7k

414 Stars in the last 64 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The app is a control plane, the compute plane is someone else's server

Hermex is a native SwiftUI client for hermes-webui, a separate MIT-licensed project maintained by another author, and the distinction is stated plainly: the phone is the control plane, not the compute plane. The agent, its tools and your data stay on hardware you control, and the app itself hosts nothing. Getting started therefore starts on the server side. You install and start hermes-webui on macOS, Linux, or Windows under WSL2, which needs Python 3.11 or newer, and you set `HERMES_WEBUI_PASSWORD`. Only then do you download the app, enter a server URL such as `https://hermes.yourdomain.com` and the password. The overview puts setup at about fifteen minutes, and it also says in one line that securing the server and keeping it reachable are your job, not the app's.

On a public hostname the password is the only application-level defense

The recommended route is HTTPS through a tunnel or reverse proxy, with Cloudflare Tunnel named as one option, terminating real TLS at a hostname you own. The stated reason is technical rather than aesthetic: real HTTPS keeps iOS App Transport Security satisfied with no exceptions. The warning that follows is the part to sit with. On a publicly reachable hostname the password is the only application-level defense the app has, so the guidance is to set a strong one. Two looser options exist and both are labelled as such. Binding directly to `0.0.0.0` over plain HTTP is described as a manual fallback rather than the default. Using a local address on a home network, such as `http://192.168.1.5:8787`, requires the server to listen on that address, which exposes it to every device on the network and is only suggested for a network you trust.

Tailscale Serve comes with a port 443 precondition

The private HTTPS option is spelled out as a sequence of conditions rather than a single command. Keep the server password-protected and bound to `127.0.0.1:8787`, inspect the Serve and Funnel routes that already exist, and only then add `tailscale serve --bg 8787`, and only when HTTPS port 443 at the root path is free. The iPhone needs Tailscale installed and connected, and the URL has to be the exact one reported by `tailscale serve status`, an `https://` address on a ts.net host. A third private path is NetBird or similar: install its app on the phone, keep it connected, and reach the server by its name or IP on that network. A fourth is for simulator work only, `http://localhost:8787` when the server runs on the same Mac. The through-line is that the app will not paper over a misconfigured network; every one of these routes depends on something outside the phone being right first.

Connection troubleshooting is four checks and one health endpoint

When connection testing fails, the overview asks for four things in order. The machine hosting hermes-webui has to be awake, since a sleeping laptop is the most common version of this problem. The server has to be running and serving its health endpoint, which can be checked directly:

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

Third, the tunnel, reverse proxy or Tailscale route has to be connected, which is a separate failure from the server being down. Fourth, the URL and the password typed into the app have to be right. Nothing in that list is a client-side bug, which is consistent with the app being a thin client, and nothing in it involves a retry policy or a stored diagnostic bundle. If all four hold and the app still refuses to connect, the project asks for the server version in the bug report, for the reason given in the next section.

Two pinned commits, two upstream projects, one hard version floor

Compatibility is handled with files rather than prose. The app is developed and tested against the hermes-webui commit pinned in `UPSTREAM_TESTED_SHA`. Bot Mode, which connects to Hermes directly rather than through the web interface, carries a second pin in `HERMES_AGENT_TESTED_SHA`, where line 1 is the tested hermes-agent commit and line 2 is the release string that server's `/api/status` reports. On top of the pins sits a refusal: Hermex rejects a host older than Hermes 0.21.3, described as the first release carrying the gateway contract the app is built on, and asks for an update instead. The reason for pinning at all is stated too. Upstream does not yet guarantee API stability and declares version skew unsupported pending stable-API work, so a newer or older server can break individual features. The app's side of that bargain is tolerant decoding, where unknown fields do not crash it, and endpoint shapes are checked against upstream source rather than invented.

The Xcode target is HermesMobile while the app on the phone is Hermex

The App Store build is the recommended path for anyone who is not developing. Building yourself needs Xcode 26 or newer with the iOS 18 SDK, plus an iPhone or simulator on iOS 18 or newer. The project file is `HermesMobile.xcodeproj` and the scheme to run is `HermesMobile`, while the display name on the device is Hermex, a split worth knowing before you go looking for a scheme named after the app. Dependencies resolve through Swift Package Manager without extra steps. From a shell, the two commands that matter are:

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

If that simulator is not installed, `xcrun simctl list devices available` lists what is there. Local validation defaults for XcodeBuildMCP users live in `.xcodebuildmcp/config.yaml`, and the standard post-change flow is written down in `DEVELOPMENT.md`.

The notification relay sees tokens and ciphertext, never message text

The privacy story is specific about the one component that could have been a leak. Push notifications are optional and stay off until they are enabled, and the relay that forwards them is open source and self-hostable. When you do enable it, that relay sees device tokens, notification metadata including kind, source, thread and session ids and timestamps, and the ciphertext of the payload. It never sees message text, server URLs, or credentials. The rest of the app follows the same shape: the app talks only to your server, with no analytics and no tracking, and sessions cached on the device stay readable offline. The two panels that would be the most sensitive, agent memory and usage analytics, are read-only by design, while the workspace browser, which walks the server's file system from the phone, is the feature that most deserves the strong-password advice.

Three releases in four weeks and a tree with more process files than targets

Version 1.6.0 went out on 2026-09-06, 1.7.0 on 2026-09-24 and 1.8.0 on 2026-10-01, with the last push on 2026-10-02. That cadence sits next to a top level that reads like a process document set: AGENTS.md, CLAUDE.md, CONTEXT.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, CHANGELOG.md, DEVELOPMENT.md and TESTFLIGHT.md. The code side is split the way an iOS app usually splits, with HermesMobile/ for the main target, HermesMobileTests/, plus three separate components that carry their own directories, HermesLiveActivityWidget, HermesNotificationService and HermesShareExtension. Config/, ci/, docs/ and scripts/ sit alongside them, and .agy/ and .xcodebuildmcp/ point at the tooling the project expects contributors to use. The repository is MIT licensed and not archived.

Editorial conclusion

Hermex is worth a look if you already run hermes-webui and want phone access to sessions, cron jobs, skills and the server filesystem, and if you are the kind of person who reads a pinned commit SHA before updating. It is not a product you can adopt on its own: the app ships no backend, so a fresh install has nothing to connect to until you stand up a third-party server, expose it, and protect it. Weigh three things before connecting a phone to it. First, the password is the only application-level defense on a publicly reachable hostname, so pick a real tunnel or a private network rather than the plain HTTP fallback. Second, the Wi-Fi option exposes the server to every device on that network. Third, upstream does not yet promise a stable API, so a server upgrade can break individual features, which is why bug reports are asked to carry the server version. Building from source adds an Xcode 26 requirement and a HermesMobile target whose name differs from the app's.

Frequently asked questions

What does the Hermex iPhone app actually do?

It is a client for a self-hosted hermes-webui agent: chat with streaming responses, steer or stop a run, browse and resume sessions, switch models, profiles and projects, view and edit scheduled cron jobs, browse installed skills, walk the server's file system, and read agent memory and usage panels. The agent and its data stay on your own hardware.

Does Hermex need its own backend server?

Yes. Hermex is a client only and does not ship, host or provision a backend. You run hermes-webui yourself on macOS, Linux or Windows under WSL2 with Python 3.11 or newer, set HERMES_WEBUI_PASSWORD, and enter that server's URL and password in the app.

Which iOS version does Hermex require?

The app needs iOS 18 or newer. Building it from source needs Xcode 26 or newer with the iOS 18 SDK, and the Xcode scheme is named HermesMobile even though the app's display name is Hermex.

What can the Hermex push notification relay see?

An open-source relay you can self-host forwards notifications and sees device tokens, metadata such as kind, source, thread and session ids and timestamps, and the ciphertext. It never sees message text, server URLs or credentials, and notifications stay off until you enable them.

How does Hermex pin which server version it works with?

UPSTREAM_TESTED_SHA holds the tested hermes-webui commit, and HERMES_AGENT_TESTED_SHA holds the tested hermes-agent commit on line 1 with the release string its /api/status reports on line 2. Hermex refuses a host older than Hermes 0.21.3 and asks you to update.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. uzairansaruzi/hermex on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/uzairansaruzi-hermex.svg)](https://hysenlabs.com/projects/uzairansaruzi-hermex)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/uzairansaruzi-hermex.svg)](https://hysenlabs.com/projects/uzairansaruzi-hermex)

Was this useful?