uzairansaruzi/hermex

Hermex – iPhone client for a self‑hosted Hermes AI agent

What it is – Hermex is a native iOS 18+ SwiftUI app that lets you control a hermes‑webui server you run yourself. The server hosts an AI agent (often a large‑language‑model‑backed chatbot) together with its tools, memory, and scheduled tasks. Hermex is only the control plane: it sends commands, streams chat, and displays data, while all model inference and data stay on your own machine.

Why it matters – It gives privacy‑first users a way to interact with their own LLM‑powered agents from a phone without any third‑party relay, analytics, or subscription fees. The app is open‑source, MIT‑licensed, and built with real SwiftUI (no web wrapper).

Core features (as described in the README)

Feature	What you can do
Chat	Send a message, choose model/provider, set reasoning‑effort, workspace and profile; attach files/images; watch a streamed response that includes tool‑call details.
Steer runs	Pause, resume or abort a generation while it’s in progress.
Sessions	Browse, search and resume any conversation stored on the server; sessions are cached locally for offline reading.
Model picker	Switch between any model the server is configured for; favourite and recent models are saved.
Profiles & projects	Change the agent’s profile (e.g., system prompt) and group sessions into projects.
Tasks	View and edit the agent’s cron‑style scheduled jobs directly from the phone.
Skills	Browse and search the list of installed “skills” (tool plugins) on the server.
Workspace browser	Explore the server’s file system from the app.
Memory & Insights	Read‑only panels showing the agent’s memory store and usage analytics.

How to get started (user‑side)

Run a hermes‑webui server on any machine you control (macOS, Linux, Windows/WSL2). It requires Python 3.11+ and the environment variable HERMES_WEBUI_PASSWORD.
Expose the server to your iPhone via one of the recommended methods:
- HTTPS tunnel or reverse proxy (e.g., Cloudflare Tunnel) – preferred.
- Private HTTPS using Tailscale Serve.
- For local testing only, http://localhost:8787 when the server runs on the same Mac.
Install Hermex from the App Store (or build from source) and enter the server URL and password.
The app will verify the /health endpoint and then let you start chatting, manage tasks, etc.

Building the app yourself

Requirements – Xcode 26 (iOS 18 SDK) or newer, an iPhone or iOS 18+ simulator.
Steps – Clone the repo, open HermesMobile.xcodeproj, and run the HermesMobile scheme. Dependencies are fetched automatically via Swift Package Manager.
CLI build example:

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

Tests can be run similarly with xcodebuild test.

Compatibility notes

The app is tested against a specific commit of hermes-webui (recorded in UPSTREAM_TESTED_SHA). Because the upstream API is still unstable, newer or older server versions may cause some features to break. The app tolerates unknown JSON fields and will display a warning (“Untested Hermes version”) if the server reports a different release.
A separate “Bot Mode” connection uses a pinned hermes-agent version (HERMES_AGENT_TESTED_SHA).

Contributing & community

Guidelines – See CONTRIBUTING.md and AGENTS.md for the coding agreement, dependency rules, and PR workflow.
Bug reports – Open an issue in the repo; there is also a SECURITY.md for vulnerability disclosures.
Support – The project is free, but the author welcomes stars, follows on X, and coffee donations.

License

MIT License (see LICENSE).
Icon assets use Apache‑2.0 and MIT‑licensed third‑party icon sets.

TL;DR

Hermex is a privacy‑focused iOS client that lets you chat with, steer, and manage a self‑hosted Hermes AI agent. It requires you to run the open‑source hermes‑webui server yourself, then connect the app over HTTPS (or Tailscale). The app is free, open‑source, and built with native SwiftUI for iOS 18+.