Case study 07 of 11
Hermes
A native app for the agent you run yourself
A native iPhone, iPad and Mac app for Hermes Agent: replies that stream every command and file change as it happens, approvals shown exactly as they will run, Bots, voice and widgets, with no account and nothing in between.
- Role
- Author and maintainer
- Platform
- iPhone, iPad and Mac
- Stack
- Swift 6SwiftUIWidgetKitSparkle
- Share
Context
Hermes Agent is the open-source agent by Nous Research that lives on your own computer: it runs commands, writes code, browses, remembers what it learns and works on a schedule. I did not build the agent. I built Hermes, the native app that puts it in your hand on iPhone, iPad and Mac. It talks only to your own Hermes, with no account and nothing in between.
An agent that runs real commands on a real machine needs a client that shows what it is doing and asks before it acts. In Hermes, replies stream in with every search, command and file change as it happens, and every command that needs approval is shown exactly as it will run, answered in the app, from a notification, the Lock Screen or the Dynamic Island.
Role & approach
The app talks to both of Hermes's servers. Chats go through the gateway's API server as detached runs streamed over server-sent events, so leaving the app doesn't stop the agent, and the app re-attaches to the stream when it comes back. Bots, the Board, the Inspector and undo go through Hermes's backend over REST and a JSON-RPC WebSocket. The API contract was taken from the Hermes Agent source, not guessed, and every new gateway call gets a mock in the same change, shaped like the real one, refusals included.
The hardest part is a message typed while the agent is busy. The app never refuses one: it can steer the running turn, redirect it, wait in an Up next queue, be asked aside or run in the background. A send matrix tests every way a message reaches Hermes against every state a chat can be in, twice: once at the model level, and once in the running app on iPhone and Mac against the mock. Its rules: nothing is lost, sent twice or sent into the wrong turn, the queue survives a reconnect and a relaunch, and a refusal is Hermes's own words, never a generic error.
The safety rules are written down beside the code. The gateway is trusted; what flows through it isn't. Pages Hermes read, project files and other Bots' messages can all carry injected instructions, so links from chats open only web pages and mail, approval text shows invisible and reordering characters as their codes, and an answer goes to the request the person saw. Notifications are sealed for the device's key with X25519, HKDF and ChaCha20-Poly1305 before they leave the gateway, and the relay that forwards them sees no content and needs no accounts.
It is one multiplatform SwiftUI app in Swift 6 with strict concurrency, with a Swift package for everything that isn't UI, three iOS extensions, a push relay, two Hermes plugins and stdlib-only Python mocks of Hermes. Every screen is held to light and dark, Increase Contrast, Dynamic Type, VoiceOver and Reduce Motion. The Mac gets its own type scale, because macOS has no Dynamic Type and a 13 pt body, too small for long-form chat.
Outcome
Hermes is in its first public beta for iPhone, iPad and Mac: on TestFlight for iPhone and iPad, and as a signed, notarized Mac download that updates itself. Every release ships iOS and macOS together. Every commit to main runs the tests and the iPhone and Mac builds on a self-hosted Mac mini, and pull requests are never built there, on purpose: the repository is public and the mini holds the signing keys.
The source is public under the MIT license, with the architecture, the safety rules and the release process documented next to the code. The app's site is hermesapp.dev.