01 / BEFORE YOU START

A few things to have ready.

Hermie is the client for Hermes Agent. Your agents run on your own machine; Hermie gives you a place to talk to them.

Node.js 22+

Use the repository’s Node version with nvm.

Platform build tools

Xcode for Apple, Android Studio for Android.

Gateway protocol 7+

A Hermes gateway reachable from your device.

Store releases are being prepared; until then, build it from source or run Hermie Web.

Coming soonApp StoreComing soonGoogle Play

Download links will appear here when the apps are available. You can follow releases on GitHub.

02 / BUILD THE APP

From source to your screen.

Clone the repository and install the dependencies.

Install dependencies
git clone https://github.com/fullstackstudio-org/hermie.git
cd hermie
nvm use
npm ci

Choose your platform to see the run command.

iPhone & iPad
npm run ios

Requires macOS and Xcode. Starts an iOS simulator build. The native project is generated on first run.

03 / CONNECT YOUR GATEWAY

Your agents are one connection away.

Start your Hermes gateway on the machine that hosts your agents. The default port is 9119.

On your gateway machine
hermes serve
  1. Enter your gateway address

    Open Hermie and enter the address your device can reach. Set dashboard.public_url on the gateway to that same address, including its scheme.

  2. Sign in

    Use the gateway’s native sign-in flow. If authentication is disabled, enter the session token printed by hermes serve.

  3. Test the connection

    The setup checks both the API and WebSocket connection before saving your configuration. A reverse proxy must pass WebSocket upgrades through.

A private network such as a tailnet is the recommended setup. Use HTTPS for a gateway exposed to the internet. Read the gateway networking guide for the full configuration.
04 / FIRST CONVERSATION

Say hello.

Your gateway’s bots appear as chats. Open one, send a message, and follow the response as it arrives. Tool calls and questions stay in the conversation.

Just looking around?

The repository includes a demo gateway with two bots and sample conversations. Run it in a second terminal from the repository root.

Demo gateway
npm run fake-gateway -- --auth token --token demo

Connect to your development machine on port 9119 with the token demo. Use its reachable address on physical devices; localhost on a phone points to the phone itself. The standard Android emulator reaches the host at 10.0.2.2.

Send a message containing “approve” to see a permission request, or “delegate” to explore subagent activity.

See what you can do with Hermie
05 / NOTIFICATIONS

Hear about it while you’re away.

Hermie can tell you when a bot answers, when an agent needs permission and when a routine delivers. The sending happens on your gateway: install the Hermie plugin into hermes serve, then turn notifications on under Settings → Notifications.

On your gateway machine
hermes plugins install fullstackstudio-org/hermie-plugin --enable
hermes gateway restart

It needs Hermes Agent 0.21 or newer and outbound access to Expo’s push service. Nothing needs to reach your gateway from outside.

Read the plugin guide
06 / IN A BROWSER

Or skip the build entirely.

Hermie Web is the same app, served by one small Node process you run next to your gateway. Nothing is installed on the device you open it from, and there is no service of ours in the path.

On your gateway machine
npx @hermie/web --gateway http://127.0.0.1:9119

It answers on http://127.0.0.1:9120 and binds to loopback until you put something in front of it. Start it without --gateway and it serves an operator setup page instead, so the gateway is configured once and everybody else only ever signs in.

Read the Hermie Web guide
07 / COMMON QUESTIONS

A few common questions.

Do I need a Hermie account?

No. Hermie connects to your own Hermes gateway and uses its authentication. There is no separate Hermie account.

Can I use more than one gateway?

Yes. Settings → Gateways keeps every gateway this device knows and switches between them with a tap. Hermie holds one connection, so switching disconnects and dials the other, but nothing is thrown away: each gateway keeps its own sign-in, its own cached conversations, its own read marks and its own arrangement. Bot-to-bot communication stays within one gateway.

Does Hermie run agents on my phone?

No. Agents run on the machine hosting Hermes. Hermie is the client. Recent cached conversations remain readable offline, but sending messages and running tasks requires a connection.

Why won’t my gateway connect?

Check that your device can reach the address, your gateway supports protocol 7 or newer, and your proxy supports WebSockets. For authenticated gateways, check native PKCE support and dashboard.public_url. See the gateway setup runbook.