Hermes for iOS

Hermes for iOS puts a real agent loop on your iPhone. Choose your own model provider, connect MCP servers, give Hermes access to supported iOS apps, and shape its personality without running the Hermes desktop or Python runtime.

The app is written in native Swift and SwiftUI. It bundles no downloadable model. Most conversations use the provider you configure, while eligible iPhones on iOS 26 or later can use Apple Intelligence as an optional on-device text provider.

Tip

Install the beta: Join Hermes Agent 0xGingi on TestFlight

Note

This project is in pre-release. You can install the public beta through TestFlight or build it from source. The automated Swift, JavaScript, and UI test suites are in place. The final release gate is the real-device matrix in RELEASE_CHECKLIST.md.

Start here

• Install the TestFlight beta
• Install from source
• Connect a model provider
• Set up Personality and Soul
• Connect MCP servers
• Use native iOS integrations
• Review privacy and local data
• Troubleshoot common setup problems

What you can do

• Chat with models through OpenAI-compatible Chat Completions, OpenAI Responses, Anthropic Messages, Gemini, or Apple Intelligence.
• Let Hermes use Reminders, Calendar, Contacts, Maps, notifications, Apple Music, registered Shortcuts, and approved links.
• Bring in pages and files through Safari, the share sheet, Photos, and Files.
• Add remote tools through MCP Streamable HTTP.
• Create a personal SOUL.md, USER.md, skills, and curated memory.
• Generate images and videos through separate compatible providers.
• Use remote speech-to-text and text-to-speech without sending a draft automatically.
• Run bounded leaf subagents and bring their results back into a conversation.
• Keep conversations, configuration, and generated artifacts in local storage.

Hermes handles streaming, Markdown, tool activity, approvals, interrupted-turn recovery, conversation titles, and context compression inside the app.

Requirements

Requirement	Details
iOS	iOS 17 or later
Mac toolchain	Xcode with Swift 6 support
Apple Intelligence	iOS 26 or later, an eligible device, and Apple Intelligence enabled
Remote models	An HTTPS generation endpoint, model ID, and credential from your chosen provider
Physical-device signing	An Apple development team and bundle identifiers you control
Hermes Agent checkout	Not required

An SDK that contains Apple's Foundation Models framework enables the Apple Intelligence adapter. Older SDKs build an unavailable fallback, so remote providers can still be used.

Install from source

1. Download or clone this repository on a Mac.
2. Open HermesIOSApp.xcodeproj in Xcode.
3. Select the HermesIOSApp target, then choose your team under Signing & Capabilities.
4. Register and use the checked-in bundle identifiers: com.0xgingi.hermes, com.0xgingi.hermes.ShareExtension, and com.0xgingi.hermes.SafariExtension.
5. Register an App Group. The checked-in identifier is group.com.0xgingi.hermes. If you replace it, use the same value in all three entitlement files and in SharedInboxStore.appGroupIdentifier.
6. Enable MusicKit for the app identifier if you want Apple Music playback.
7. Select your iPhone and press Run.

The main app target supports iOS 17. Apple Intelligence, Safari extension behavior, Apple Music, permission flows, and several other native integrations need a compatible physical device for meaningful testing.

First run

Hermes opens model-provider setup when no active provider exists.

1. Choose a protocol.
2. Enter the full request endpoint, model ID, and credential. Apple Intelligence needs none of these.
3. Save the profile.
4. Use Test Connection from the provider's action menu.
5. Start a new conversation and choose the provider.

A connection test makes one small generation request and may cost a small amount. The Apple Intelligence test runs locally and checks model readiness.

Provider routes are frozen when you create a conversation. Editing a model, endpoint, provider credential, MCP selection, or Personality affects new conversations. It does not quietly change the identity or authority of an existing chat.

Model providers

Open Settings > Model Providers to add, test, edit, disable, or archive a provider.

Protocol	Use it for
Chat Completions	OpenAI-compatible services, including OpenRouter and custom endpoints
OpenAI Responses	Providers that implement the OpenAI Responses API
Anthropic Messages	Direct Anthropic Messages endpoints
Gemini	Gemini streamGenerateContent endpoints
Apple Intelligence	Apple's on-device Foundation Models framework

For remote providers, enter the complete generation endpoint. A host URL or dashboard URL is not enough. For example, a Chat Completions profile normally ends in /v1/chat/completions, while a Responses profile normally ends in /v1/responses.

Hermes requires HTTPS for remote credentials. Anonymous loopback HTTP is available for local development, but the app never sends a bearer credential over plaintext HTTP. Provider secrets live in the iOS Keychain, not SQLite.

Apple Intelligence

Apple Intelligence is an optional text provider. Hermes still owns the agent loop, validates proposed tool calls, and presents the same approval screens. Apple's model does not execute effects by itself.

The current Apple route has several firm limits:

• It requires an eligible device on iOS 26 or later.
• It accepts text only.
• It returns complete responses instead of token-by-token streaming.
• It does not expose provider reasoning or token-usage reports.
• Its context window is 4,096 tokens. The app cannot increase that system model limit.

Hermes packs recent history and selects only the tool schema needed for a turn, but a large Personality, current message, or tool result can still exceed the limit. Remote providers remain the practical choice for long conversations, large MCP catalogs, image input, and larger context windows.

Personality and Soul

Open Settings > Personality to decide who Hermes should be and what it should know about you.

Section	Owner	Purpose
SOUL.md	You	Voice, values, boundaries, and behavioral guidance
USER.md	You	Information that should accompany every new conversation
Agent Soul	You and Hermes	Lower-priority notes that Hermes may propose changing

Hermes cannot edit your SOUL.md or USER.md. It can propose a complete replacement for Agent Soul through ios_update_agent_soul, but the app shows the full replacement and reason before you approve it. A stale proposal cannot overwrite a newer edit.

The app copies the complete Personality into each new conversation. Existing conversations keep the snapshot they started with. USER.md is sent to the selected model provider in every new chat, so keep passwords, API keys, and other secrets out of it. Put facts that matter only sometimes in Memory.

Skills

Skills are local Markdown instructions that you can call by name. Open Settings > Skills to create one with a slash command, description, and instructions.

You can invoke a skill at the start of a message:

/review check this API design

Up to five skills can be stacked in one turn:

/research /concise explain this paper

The transcript keeps the short command while the selected model receives the matching instruction text. Every invocation stores the skill revision used for that turn, so later edits do not rewrite old conversations.

iOS skills are instruction-only. They cannot run shell scripts or read bundled supporting files. Expose those capabilities through MCP or a registered Apple Shortcut instead.

Memory

Open Settings > Memory to add facts or working notes that Hermes may recall. Memory is explicit and user-managed. The app never learns from a conversation or saves a memory silently.

You can edit, disable, or forget each entry. Hermes ranks enabled memories on the phone and sends at most five relevant entries, within a 12 KB limit, to the selected model. Entries marked for every turn skip relevance ranking.

For an external memory service, Settings > External Memory supports Hindsight retain, recall, and reflect. Each external call requires approval. Other memory services can be connected through MCP.

MCP servers

MCP adds remote tools without changing this app or Hermes Agent.

1. Open Settings > MCP Servers.
2. Choose Connect Server.
3. Give the server a namespace such as firecrawl or home.
4. Paste the exact MCP Streamable HTTP endpoint from the server's documentation.
5. Choose anonymous, bearer-token, or OAuth authentication.
6. Connect, inspect the discovered tools, and select the tools you want new conversations to receive.

The namespace is only a short local name that keeps tools from different servers distinct. It does not change the request URL and does not need to match a vendor account or remote namespace.

Hermes supports paginated tool discovery, JSON and server-sent-event responses, OAuth with PKCE, and optional TLS public-key pinning. Use pinning only with a fingerprint obtained through a trusted channel.

Every MCP call requires approval because it sends arguments to a remote server and that server may have side effects. The approval shows the server, tool, and arguments. Completed tool activity appears as a compact card in the transcript, not as a series of chat messages.

MCP tools are frozen per conversation. Reconnect or start a new chat after changing the selected tools. The combined native and MCP catalog is limited to 128 tools.

Native iOS integrations

Hermes uses public iOS frameworks and asks only when an action needs data or can change something.

Integration	Available actions
Reminders	Create, list, complete, update, and delete reminders
Calendar	Create, list, update, and delete events
Contacts	List, create, update, and delete supported contact records
Location and Maps	Get one foreground location fix, search places, request directions, and open Maps
Apple Music	Search the catalog, read playback state, play an exact result, pause, and resume
Notifications	Schedule, list, and cancel one-time Hermes notifications
Apple Shortcuts	Run exact actions registered in Hermes settings
Links	Open approved web, universal, and supported app links
Date and time	Read the device's current date, time, weekday, and time zone

Personal-data reads show a disclosure before Hermes returns anything to the model. Mutations show the exact proposed change. If iOS cannot prove whether an approved action completed, Hermes asks you to reconcile the result instead of repeating it.

iOS does not permit general control of other apps. Hermes can use the native integrations above, open approved links, and run Shortcuts that you registered. It cannot inspect another app's private data, tap its interface, or execute arbitrary URL schemes in the background.

Apple Shortcuts

Create the Shortcut in Apple's Shortcuts app first. Then open Settings > Shortcut Actions in Hermes and register its exact name and allowed input type. Hermes can launch only registered actions, and every launch requires approval.

The bridge does not claim to read a Shortcut's result or know that it finished. After handoff, Hermes asks you to confirm what happened.

Safari and the share sheet

There are two ways to bring a page into Hermes:

• Use Share > Hermes in Safari to capture the URL, title, and selected text.
• Enable the Hermes Safari extension and tap its page action. You can choose whether to include up to 64 KB of visible page text.

The Safari extension has no persistent content script, host-wide page access, browsing-history permission, cookies, or network connection. It reads the active page only after you tap it.

Text, links, and supported images from Safari, Photos, Files, and other apps go to Shared with Hermes. Nothing reaches a model until you add the item to a draft and press Send. The Ask Hermes Siri and App Intent uses the same review inbox instead of running inference inside an extension.

Images, files, and voice

The composer can import selected images from Photos, supported images from Files, and UTF-8 text files. Hermes normalizes image input before sending it. A single message can contain up to eight images and 24 MB of image data. Text files can be up to 256 KB each, with a 512 KB combined text-import limit.

Multimodal input needs a remote provider and model that accepts images. Apple Intelligence is text-only in this app.

Open Settings > Voice to configure remote OpenAI-compatible transcription and speech endpoints. Hold the microphone beside the composer to record. The transcript enters the draft for review and never sends automatically. Speech playback can be started for a completed reply or enabled for future completed replies.

Recordings are temporary and limited to 60 seconds. Transcription and speech keys use separate Keychain records.

Image and video generation

Image and video generation use separate provider profiles. They do not reuse the model-provider credential unless you configure the same service yourself.

• Settings > Image Generation accepts OpenAI Images-compatible HTTPS endpoints that return inline base64 PNG or JPEG data.
• Settings > Video Generation accepts an OpenAI Videos-compatible create, poll, and download flow.

Hermes asks before a billable generation request. Finished files become protected local artifacts that you can preview, share, save to Photos, or delete. The app does not follow provider-returned image URLs. If an interrupted request may already have created or billed for media, Hermes does not submit it again automatically.

Leaf subagents

Hermes can start bounded leaf subagents for focused work. A leaf uses either no tools or one to eight MCP tools already available to the parent conversation. It cannot use native iOS tools, memory, media generation, or another subagent.

Each result appears in its own card. Tap Use result to add it to the parent conversation. Relaunch recovery prevents the same result from being inserted twice.

Conversation behavior

Titles

New chats begin as "New conversation." After the first successful response, Hermes asks the selected provider for a short title based on the actual topic. If title generation fails, the conversation remains usable and keeps its placeholder title.

Context compression

After more than four completed user turns, open the conversation menu and choose Compress earlier context. Hermes asks the conversation's remote provider for a no-tools summary of older completed turns. The full transcript stays on the phone, while later requests use the summary and recent messages.

Remote provider profiles can also enable automatic compression when you enter the provider's exact context capacity and reserved output budget. Hermes does not guess context size. Compression is unavailable when the covered range contains an image.

Apple Intelligence cannot report token usage, so it does not support the automatic trigger. Hermes instead packs the newest usable history into Apple's fixed context on each turn.

Interrupted work

Provider requests and effects use durable checkpoints. If the app closes during a request, it offers the safe next action after relaunch. Hermes retries only when it can prove the original request did not cross the dispatch boundary. An unknown outcome requires your confirmation.

Privacy and local data

Hermes for iOS has no first-party inference proxy. A remote conversation goes straight to the endpoint in its provider profile. Apple Intelligence text inference uses Apple's on-device Foundation Models framework.

The app stores these items locally:

• Conversations, settings, skills, memory, tool snapshots, and recovery state in a protected SQLite database.
• Provider, MCP, generation, speech, and memory-service credentials in the iOS Keychain.
• Generated and imported artifacts in protected app storage.
• Shared items in the App Group inbox until you import or discard them.

The selected model receives the current conversation projection, frozen Personality, invoked skills, recalled memory, attachments, and tool results as needed. An MCP server receives only the approved tool call and arguments. A native personal-data read reaches the model only after its disclosure approval.

The current app targets declare no tracking and no tracking domains. See PRIVACY.md for the release privacy notes.

Open Settings > Data & Storage to:

• Export a conversation as readable Markdown or structured JSON.
• Browse, share, save, or delete generated artifacts.
• Preview the exact scope of conversation deletion.
• Delete individual conversations.
• Reset all local data, optionally also removing account setup and Keychain credentials.

Exports never contain Keychain credentials.

Important limits

Hermes for iOS is a native iPhone agent, not the desktop runtime inside an app sandbox.

• It has no terminal, arbitrary filesystem, SSH, Docker, or local Python plugin execution.
• It does not run Telegram, Discord, Slack, email, or other Hermes messaging gateways.
• It has no always-on daemon or cron runner. iOS background time is finite and opportunistic.
• It cannot automate arbitrary browser tabs or other apps. Use Safari sharing, native integrations, a registered Shortcut, or an MCP server.
• Python Hermes plugins work only when they expose a supported public provider protocol or MCP server.
• Provider fallback and automatic model routing are not implemented. Each conversation has one frozen provider route.
• Some strict MCP OAuth servers reject private app-scheme callbacks. A publisher-owned HTTPS callback and Associated Domain are still required for universal OAuth compatibility.

The detailed capability boundary lives in FEATURE_PARITY.md. The standalone contract lives in COMPATIBILITY.md.

Troubleshooting

A custom provider returns invalidJSON

Check that the profile protocol matches the endpoint. Paste the full generation URL, not the provider homepage or API base. Confirm the model ID and credential, then run Test Connection. HTML error pages, reverse-proxy login pages, and a Chat Completions response sent to a Responses profile can all appear as invalid JSON.

Apple Intelligence says the request exceeds 4,096 tokens

The 4,096-token limit comes from Apple's system model and cannot be raised by the app. Even a short question also includes the frozen Personality, recent history, and selected tool information.

Shorten SOUL.md, USER.md, or Agent Soul, disable unneeded MCP tools, and start a new conversation. If the newest message or a tool result is large, shorten it. Use a remote provider when the task needs a larger context window.

A setting changed, but the current chat still uses the old value

Start a new conversation. Provider routes, Personality, tool selections, skills used in past turns, and capability snapshots are intentionally immutable inside an existing conversation.

An MCP endpoint returns 404

Use the exact Streamable HTTP endpoint published by the MCP server. A service's website, REST API root, older SSE route, and MCP endpoint may all be different. The namespace is only a local label and does not alter the URL.

A local or LAN endpoint will not connect

Allow Local Network access for Hermes in iOS Settings. Authenticated endpoints must use HTTPS. Plain HTTP is accepted only for anonymous loopback development.

A native tool cannot read or change data

Check Hermes under iOS privacy settings for the relevant service. If access was denied or later revoked, iOS may require you to restore it in Settings. Hermes still asks for in-app approval after the system permission exists.

Hermes is missing from Safari or the share sheet

Enable the Hermes extension in Safari's extension settings. In the share sheet, open the action editor and add Hermes to the visible actions. Shared items then appear in the app's review inbox.

Development

The repository is self-contained. Do not add a package reference to a parent Hermes Agent checkout or require an unreleased Hermes core change.

Run the standalone boundary check:

./scripts/verify-standalone.sh

Run the Swift package tests:

swift test --package-path HermesIOSCore

Run the extension tests:

node --test HermesShareExtension/Tests/SafariPreprocessing.test.js
node --test HermesSafariWebExtension/Tests/Capture.test.js

Verify compiler-managed localizations:

./scripts/verify-localizations.sh

Build every app and extension target for Apple Silicon and Intel Simulator hosts without signing:

./scripts/build-simulator-universal.sh

Run the deterministic UI scenarios on a disposable Simulator:

./scripts/test-ui.sh

Run the complete host-side release gate:

./scripts/verify-pre-xcode-release.sh

The UI runner exits with status 77 when no iOS Simulator runtime is installed. See RELEASE_CHECKLIST.md for formatting, recovery, signing, App Store metadata, and real-device release checks.

Project documents

• Feature parity records native, bridged, limited, and absent Hermes capability families.
• Compatibility contract defines the standalone repository boundary.
• Privacy notes describe current data flow and App Store privacy work.
• Release checklist is the release-candidate gate.

License

Hermes for iOS is available under the MIT License.