Hermex

Control your self-hosted Hermes agent from your iPhone.

Your server. Your iPhone. No middleman.

Website · App Store · Report a bug · Contributing

Hermex is a native SwiftUI iPhone app for driving a self-hosted hermes-webui server — a mobile cockpit for an AI agent that lives on a machine you control. The phone is the control plane, not the compute plane: the agent, its tools, and your data stay on your own hardware.

• Free. No subscriptions, no in-app purchases.
• Private. No analytics, no tracking. The app talks only to your server. Push notifications are optional and off until you enable them: an open-source relay you can self-host forwards them, seeing device tokens, notification metadata (kind, source, thread and session ids, timestamps), and ciphertext. It never sees message text, server URLs, or credentials.
• Native. Real SwiftUI, built for iOS 18+, not a web wrapper.

Features

• Chat with your agent — send messages with model, reasoning-effort, workspace, and profile options; attach files and images; watch responses stream in real time with thinking and tool-call detail.
• Documents in direct-Hermes chats — tap a PDF or other supported MEDIA: document to read it in Quick Look, then save or share it.
• Steer or stop a run mid-flight.
• Sessions — browse, search, and resume every conversation on your server; cached sessions stay readable offline.
• Pick your models — switch between any model or provider your server is configured for, with recents and favorites.
• Profiles & projects — switch agent profiles and organize sessions into projects.
• Tasks — view and edit your agent's scheduled cron jobs from your phone.
• Skills — browse and search the agent's installed skills.
• Workspace browser — explore your server's file system from the app.
• Memory & Insights — read-only panels for agent memory and usage analytics.

More screenshots at hermexapp.com.

Getting started

Hermex is a client only — it does not ship with, host, or provision a backend. You bring your own hermes-webui server (a third-party, MIT-licensed open-source project) running on a machine you control. Setup takes about 15 minutes:

1. Run the server. Install and start hermes-webui on macOS, Linux, or Windows/WSL2 (Python 3.11+). Set HERMES_WEBUI_PASSWORD.
2. Make it reachable from your phone (see options below).
3. Connect. Download Hermex, enter your server URL (e.g. https://hermes.yourdomain.com) and password, and you're in.

Running a Hermes host instead? Hermex can also sign in to Hermes's own dashboard (hermes dashboard, port 9119). Onboarding's first step gives your agent a prompt that sets it up: username and password sign-in under dashboard.basic_auth, a persistent dashboard.basic_auth.secret so sign-ins survive a restart, and dashboard.public_url set to the address your phone uses, reached through one of the options below. Those examples use the Web UI's port 8787; substitute your dashboard's port (9119 by default) in addresses and forwarding commands. Hermes refuses to serve beyond 127.0.0.1 without that sign-in.

Self-hosting the server, securing it, and keeping it reachable are your responsibility.

Making the server reachable

• HTTPS via a tunnel or reverse proxy (recommended). Expose the server through Cloudflare Tunnel or any reverse proxy that terminates real TLS at a hostname you own. Real HTTPS keeps iOS App Transport Security happy with no exceptions. On a publicly reachable hostname the password is your only app-level defense — set a strong one.
• Private HTTPS with Tailscale Serve. Keep the server password-protected and bound to 127.0.0.1:8787, inspect existing Serve/Funnel routes, then add tailscale serve --bg 8787 only when HTTPS port 443 at the root path is free. Install Tailscale on the iPhone and connect with the exact https://…ts.net URL reported by tailscale serve status. Direct binding to 0.0.0.0 over plain HTTP remains a manual fallback, not the default.
• Another private network, such as NetBird. Install its app on the iPhone, keep it connected, and use the server's name or IP on that network.
• Same Wi-Fi. On a home network you trust, use the machine's local address and port, such as http://192.168.1.5:8787. The server must listen on that address rather than only 127.0.0.1, which exposes it to every device on the network, so keep the password strong.
• Simulator-only local testing can use http://localhost:8787 when the server runs on the same Mac.

Troubleshooting the connection

If connection testing fails, check these first:

1. The machine hosting hermes-webui is awake.
2. hermes-webui is running and serving /health (curl https://<your-server>/health).
3. The tunnel, reverse proxy, or Tailscale route is connected.
4. The server URL and password are correct.

Building from source

Prefer the App Store build unless you're developing. To build yourself you need Xcode 26 or newer (iOS 18 SDK) and an iPhone or simulator on iOS 18+.

Clone the repo, open HermesMobile.xcodeproj, and run the HermesMobile scheme on an iPhone simulator (the Xcode target is HermesMobile; the app's display name is Hermex). Dependencies are resolved automatically via Swift Package Manager.

From the command line:

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

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

If that simulator is not installed, list available devices and choose a nearby iPhone simulator:

xcrun simctl list devices available

Local validation defaults for XcodeBuildMCP users live in .xcodebuildmcp/config.yaml; the standard post-change flow is in DEVELOPMENT.md.

Server compatibility

The app is developed and tested against the hermes-webui commit pinned in UPSTREAM_TESTED_SHA. Upstream does not yet guarantee API stability (its README declares version skew unsupported pending their stable-API work), so newer or older server versions may break individual features — please include your server version in bug reports. The app decodes tolerantly (unknown fields never crash it) and endpoint shapes are verified against upstream source, never invented.

Bot Mode's direct-Hermes connection has its own pin, HERMES_AGENT_TESTED_SHA: line 1 is the tested hermes-agent commit and line 2 the release string its /api/status reports. Hermex refuses a host older than Hermes 0.21.3, the first release with the gateway contract it is built on, and asks you to update Hermes; 0.21.3 and later connect without a warning.

Documentation map

• AGENTS.md: the working agreement — product boundaries, server-contract rules, locked dependencies, verification, and PR flow.
• DEVELOPMENT.md: local development workflow, server setup notes, and the maintainer release runbook.
• TESTFLIGHT.md: maintainer-only TestFlight/App Store Connect operations.
• SECURITY.md: how to report a vulnerability.
• docs/agents/: repo-local agent workflow conventions (issues, triage labels, domain notes).
• GitHub Issues: source of truth for active bugs, polish notes, and feature requests.

Contributing

Contributions are welcome — see CONTRIBUTING.md for how to pick up work and open a PR, AGENTS.md for the working agreement coding agents follow in this repo, and the Code of Conduct. The short version:

• Do not invent API endpoints or JSON shapes; verify against the upstream server source or a running server.
• Every Codable model decodes tolerantly — never crash on unknown fields.
• Add no third-party dependencies beyond the locked list in AGENTS.md without explicit approval.
• Do not modify the upstream hermes-webui server from this repo.

Support the project

Hermex is free and built in the open. If it's useful to you:

• ⭐ Star this repo — it helps others find the project.
• 🐦 Follow @uzairansar on X for updates and dev logs.
• ☕ Buy me a coffee to support development.
• 💬 Join the Hermex Discord for help, updates, and to talk with other users.
• 💛 Become a member for early TestFlight builds, the members-only Discord channels, and a vote on what gets built next.

Supporters

Hermex is funded by its members. Thank you.

Patrons: Robin Edwards

Members: Aaron Kaufer

Founding members: James Cross · Alexey

Updated monthly from Buy Me a Coffee. Members who join anonymously aren't listed. Email [email protected] to be added or removed.

License

MIT — see LICENSE.

The file-type icons in the workspace tree are Pierre's @pierre/trees icons (Apache-2.0) with six additions from T3 Code (MIT).

Hermex is an independent client and is not affiliated with the upstream hermes-webui project. Apple, the Apple logo, and App Store are trademarks of Apple Inc.