# Getting started with Hermit

Hermes is an AI agent that lives on your own computer, signed in to your accounts, working on a schedule. Hermit is how you reach it from your iPhone, iPad or Mac.

Completely new to this? Hermit needs two things on a computer you own: Hermes Agent, which runs your assistants, and Tailscale, which lets your phone reach it privately. "Starting from scratch" below walks through both installs, then "Setup, step by step" connects the app.

## What Hermit is

Hermit is an app for iPhone, iPad and Mac that lets you talk to your own AI assistants the way you text people. Each assistant has a face and a place in an inbox, like a contact in Messages.

The assistants themselves come from [Hermes Agent](https://github.com/NousResearch/hermes-agent), a separate open-source program that runs on a computer you own. Hermes does the thinking and the work: reading mail, checking a calendar, running scheduled jobs. Hermit is the window onto it.

### Why not just ChatGPT or Claude?

A chat app can only tell you what to do. A Hermes bot does it, because it has four things a chat app doesn't:

- **It has hands.** It runs commands and scripts on your own computer, and reads and writes your files.
- **It has a clock.** It works on a schedule and keeps watch while you sleep, then taps you on the shoulder only when something needs you.
- **It's signed in.** Mail, calendar, Notion, Linear, GitHub and more, so it acts where your work actually lives, not in a copy you pasted.
- **It's yours.** It remembers your people and projects across months, runs the model you choose, and keeps it all on your machine.

### The idea behind it: bots first

Hermit is built for a bot-first way of working. You don't have one general assistant that does everything. You have several **bots**, each a separate Hermes profile, and each one owns a lane.

A bot is effectively its own independent harness. It has:

- **Its own lane:** a job it's responsible for, and a personality written for that job
- **Its own context:** one permanent conversation and its own memory, so finance never crowds out family logistics
- **Its own skills:** the procedures it has learned and keeps improving
- **Its own connectors and tools:** only the services that lane needs, so the sales bot can't touch the cloud account
- **Its own model and routines:** a cheap fast model for triage, a stronger one for hard work, and scheduled jobs that run without you

Separation is what makes each bot good at its job. The cost is that you'd otherwise be juggling a dozen separate chats. Hermit's job is to remove that cost:

- **One place to work with all of them.** Every bot is a contact in one inbox, with one search, one list of what's waiting on you, and one summary across them.
- **Bots can talk to each other.** A bot can hand work to another bot, and the chat shows it as a quiet line, such as "Handed off to Marketing", that you can open and read.
- **You can orchestrate.** Put two to six bots in a group chat, or let one bot coordinate the others, while each keeps to its own lane and tools.

Three things follow from that, and they explain most of what comes later:

- **Hermit has no server of its own.** There is no Hermit account and nothing hosted. The app connects straight to your computer.
- **Your computer has to be on.** The assistants live there, so if it sleeps or goes offline, the app has nothing to talk to.
- **The app is called Hermit, the assistant software is called Hermes.** Screens that say "Connect to Hermes" mean your own computer.

### An example: one founder's setup

This is the setup Hermit was built around, with names removed: one person running a small software company, plus home life, on a single always-on Mac.

| Area | Bot | Its lane |
| --- | --- | --- |
| Running the day | Chief of Staff | Sorts the inbox, drafts email for approval (never sends by itself), manages the calendar, sends a morning brief |
| Product | Product Management | Roadmap, backlog and what's worth building |
| Product | Product Owner | The front door to the coding agents: takes a request and hands the build work on |
| Product | Agitator | Raises one pointed product question each weekday |
| Engineering | DevOps | Builds and releases, reliability and cost |
| Engineering | Compliance | Keeps checking the code and cloud setup against regulatory requirements |
| Business | CFO | The company's finances |
| Business | Investor Relations | The investor pipeline and those relationships |
| Business | Sales Lead | The sales pipeline |
| Business | Marketing | Outbound marketing |
| Business | Social | Drafts social posts |
| The system itself | Hermes Sysadmin | Looks after the Hermes installation and the other bots |
| Home | Family | Household logistics |
| Home | Fitness | Personal coaching |

A typical day shows why the lanes matter. Chief of Staff's morning brief arrives as a notification. A reply it drafted waits as a card until you edit and send it. A question for Product Management turns into a handoff to Product Owner, and you watch both faces while they work. DevOps asks permission before running a command, and you allow it from the Lock Screen. None of them sees the others' memory or uses the others' tools, and all of it happens in one inbox.

You don't need fourteen bots to start. One or two with clear lanes is enough, and the app works the same way.

## From a first chore to a team

Start at level 1. Each level builds on the one before, and most people reach the pipelines sooner than they expect. The quoted lines are prompts: paste one into a bot's chat as it stands, or change the details to fit.

| Level | What it unlocks | What it uses |
| --- | --- | --- |
| 1. Hand it a chore | One-off jobs on your own computer, done rather than explained | Your files, commands |
| 2. Put it on a schedule | Routines that run on time, whether or not you remember | Schedules, mail, calendar |
| 3. Let it keep watch | It checks for you and stays quiet until something changes | Schedules, the web |
| 4. Let it act for you | It does the next step itself and asks before anything you'd want to see first | Connectors, approvals |
| 5. Build a pipeline | Several steps that run end to end, with little to no input from you | Schedules, connectors, commands, the web |
| 6. Run a team | A few bots with their own jobs and memory, handing work to each other | Several bots, everything above |

### Level 1: Hand it a chore

**Tidy up**

> File every invoice in Downloads by vendor and month, and delete installers older than 30 days.

**Find out why**

> My Mac feels slow. Work out why and tell me what you'd change before you change anything.

### Level 2: Put it on a schedule

**Morning brief**

> Every weekday at 6:30, send me today's meetings, anything in my inbox that really needs me, and any clashes.

**Money check**

> On the 1st of each month, read my card statements in email and tell me about new subscriptions and price rises.

### Level 3: Let it keep watch

**The slot you need**

> Check the passport office's booking page every 15 minutes and tell me the moment a slot opens before June.

**Is it up?**

> Every 5 minutes, check my website and the backup drive. Only tell me if something's wrong.

### Level 4: Let it act for you

In Hermit, the step that needs you arrives as a card: a draft to edit and send, or a question to approve. All of them also wait in *Waiting on You*.

**Scheduling**

> When someone asks to meet, find a time that works, draft the reply, and send it once I approve.

**After the call**

> After each customer meeting, draft the follow-up email and update the deal in our CRM.

### Level 5: Build a pipeline

**Sales: meeting briefs.** Walk into every meeting already knowing the room.

1. Tomorrow's calendar
1. Research each company and attendee online
1. Past emails and CRM notes
1. A one-page brief before each meeting

> Every evening at 8, look at tomorrow's meetings. For each one with people outside my company, research the company and every attendee online (recent news, funding, role, anything they've published), check our past emails and CRM notes, and send me a one-page brief with talking points and open questions. Don't contact anyone.

**Product: research to requirements.** Turn what the market is saying into work your team can pick up.

1. Competitor changelogs, reviews and forums
1. A weekly intel brief in Notion
1. Top themes become draft requirements
1. Issues in Linear for your review

> Every Monday, read our competitors' changelogs, new app reviews, and forum threads about our category. Write an intel brief in Notion with what changed and what customers are asking for. For the top three themes, draft a short requirements doc and open Linear issues in Triage for me to review.

**DevOps: always on call.** Fix the routine problems itself, and wake you only for the rest.

1. Health checks every 5 minutes
1. Runbook fix: restart, clear space, roll back
1. An incident with logs in Linear
1. Pages you only if the fix didn't work

> Every 5 minutes, check our services' health endpoints, error rates and disk space. If something's wrong and it's in the runbook, apply the fix and note what you did. If that doesn't clear it within 10 minutes, open an urgent Linear incident with the logs attached and message me.

### Level 6: Run a team

This is the bot-first setup described above: each bot keeps its own lane, and they hand work to each other. The founder's setup is one example. Three more:

**A product team.** Research flows into product, product into engineering, and ops watches what ships.

- A researcher bot gathers market signals
- A product bot turns them into requirements
- An engineering bot opens draft fixes and PRs
- An ops bot watches releases and escalates to you

**A small shop.** The back office runs itself while you serve customers.

- A support bot answers routine email
- A stock bot reorders before you run out
- A books bot reconciles receipts monthly and flags gaps

**A research lab.** Keep up with your field without losing your evenings.

- A reader bot scans new papers each night
- A lab bot reruns the promising ones in a notebook on your Mac
- A writer bot sends the group a Friday digest

## Ask your own Claude

Not sure which bots fit your life, or where to start? Hand this guide to the assistant you already use and let it plan with you.

1. Copy the prompt and guide together (the button on the web page does this), or give your assistant this page's address.
2. Start a new chat in Claude, or any assistant you like, and paste.
3. Answer its questions.

```text
I'm thinking about running Hermes Agent at home and using the Hermit app to talk to it. The guide below explains both. Ask me a few questions first: what I do for work, what fills my week at home, and what computer I could leave on. Then:

1. Suggest two or three bots to start with. For each, give a name, its lane in one sentence, and what it may do without asking me.
2. For each bot, write one level 1 chore and one level 2 routine I could try in my first week, as prompts I can paste.
3. Say which connections each bot needs (mail, calendar, Notion, Linear, GitHub) and which I should leave off for now.
4. Point out anything that would get in the way, such as a laptop that sleeps.

Keep it plain and don't assume I'm technical.
```

Your Claude can't see your computer or your accounts, so what you get is a plan, not a setup. Once Hermes is running, ask your first bot the same questions: it can see what's actually there.

## How the pieces fit

The app on your device talks to two programs on your computer, and to nothing else.

The Hermit app on your device reaches your computer over Tailscale. On the computer, Hermes Agent runs your bots and the bridge handles live updates, push, faces and summaries. The bridge passes alerts to Apple's push service and sends the mail you approve through Google.

**Hermes** runs the bots. The **bridge** is Hermit's own small helper beside it: it streams replies as they're written, sends notifications through Apple, and sends the mail and invitations you approve on a card. **Tailscale** joins your devices and the computer into a private network, so none of this is open to the internet.

## Look before you set anything up

The fastest way to understand Hermit is the demo, which needs no computer, no Hermes and no account.

1. Install the app (see Setup, step 1).
1. On the first screen, tap **Try a Demo**.

You get six made-up bots with full chats, cards, summaries, profiles and settings. You can send a message and a made-up bot streams a reply that says it's a demo. Nothing is sent anywhere.

If all you want is to see what the app is, you can stop here.

## What you need for the real thing

| You need | Why | Notes |
| --- | --- | --- |
| A computer that stays on | Hermes and your bots run there | A Mac is the tested path. Linux with systemd works in a test box, and no real server has tried it yet. |
| Hermes Agent, installed and working | It is the assistant | Installed in `~/.hermes`, with at least one bot you can already chat with |
| [Tailscale](https://tailscale.com) on the computer and on each device | The private connection between them | Free for personal use. Sign in to the same account on both. |
| An iPhone or iPad on iOS 18 or later, or a Mac | To run Hermit | Apple silicon or Intel for the Mac app |

### Starting from scratch: Hermes and Tailscale

Never run Hermes before? Two installs get you to Setup. Both go on the computer that stays on: a Mac mini on a shelf is ideal, and a laptop works while it's awake.

1. **Tailscale**, on that computer and on each iPhone, iPad or Mac you'll use, signed in to the same account. It lets your devices reach the computer from anywhere, privately. [Get Tailscale](https://tailscale.com/download).
1. **Hermes.** Open Terminal and run the command below. It walks you through picking a model, from Claude or GPT with your own key to a free one running on the Mac.

```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```

Once you can chat with Hermes in Terminal, come back to Setup. The [Hermes documentation](https://hermes-agent.nousresearch.com/docs) covers the rest.

Optional, each for one feature:

- **Push notifications** need an Apple push key on the computer, which takes an Apple Developer account.
- **Sending mail and meeting invitations from a card** needs the `gog` command-line tool signed in to a Google account.
- **Voice calls** need a ChatGPT (Codex) sign-in in Hermes, or an OpenAI API key.
- **Reading Messages and Notes** is Mac-only and needs `imsg` and `memo` from Homebrew.

## Setup, step by step

About 15 minutes if Hermes and Tailscale already work.

1. **Install the app.**
    - iPhone or iPad: install Apple's TestFlight app, then open the [public beta link](https://testflight.apple.com/join/gqEdje6f).
    - Mac: download the latest disk image from the [hermit-bridge releases page](https://github.com/ellingtonsp/hermit-bridge/releases) and drag Hermit to Applications. It updates itself after that.
1. **Install Hermit's helper on the computer.** There are two ways. The easy one: tap Copy Setup Prompt on Hermit's first screen and send it to a Hermes bot you already talk to, which installs the plugin and runs setup for you. Or do it yourself in a terminal on the computer that runs Hermes:
    ```bash
    hermes plugins install ellingtonsp/hermit-bridge --enable
    hermes hermit setup --check   # reports what's ready and changes nothing
    hermes hermit setup           # asks before each change
    ```
    Setup gives every bot a key, switches the plugin on, starts a small background service called the bridge, and prints an **address** and a **short code**.
1. **Pair.** Open Hermit, type the address and the code on the first screen. The code works once and expires in 10 minutes. If it lapses, run `hermes hermit setup` again for a new one.
1. **Check the connection.** In **Settings → Connection**, Hermes should say Connected and Live updates should say On. Push says Ready only if you set up the push key.
1. **Say hello.** Open a bot from the inbox and send a message. The reply should appear a word at a time.

If you used **Copy Setup Prompt**, the bot replies with the same address and short code for step 3.

On Linux, an administrator also runs `loginctl enable-linger <you>` once, so the bridge keeps running after you log out.

If something doesn't work:

| What you see | What to check |
| --- | --- |
| Can't reach Hermes | Tailscale is on and signed in on the phone and the computer |
| Replies arrive all at once | Settings → Connection → Live updates is Off, so the bridge isn't running. Run setup again. |
| Brief errors across the app | Hermes is restarting. It's back in about 20 seconds. |
| No notifications | Push needs the Apple key. Everything else works without it. |

The [project README](https://github.com/ellingtonsp/hermit-bridge) has the longer troubleshooting list.

### Keeping the helper up to date

Hermit is two pieces that update separately. The app updates through TestFlight, or by itself on the Mac. The helper on your computer (the plugin and the bridge) only updates when you tell it to.

When a newer helper is out, the inbox shows a **Plugin update** notice above the search field. Tap **Update** and confirm. Every bot restarts, so a reply in progress stops, and they're back in about a minute. The same button is in Settings.

Don't put this off. New features in the app usually need the newer helper, and an app that's ahead of its helper just lacks them without saying why. If something described here is missing for you, check for this notice first.

A helper that was copied onto the computer by hand can't be updated from the app. The notice says so, and you update it on the computer.

## A tour of the app

The app opens on the **inbox**: every bot and group chat in one list, newest activity first.

| Where | What it's for |
| --- | --- |
| A bot's row | Opens its chat. The row says "Working" while it's busy, and "Needs your OK" or "Draft ready" when it wants you. |
| Pinned faces at the top | Your most-used bots. A ring means working, a red ring means it needs you. |
| Search | Finds bots, and messages inside every bot's chat |
| Waiting on You | Every question, approval and draft from every bot, answerable in one place |
| Tidings | A feed of suggestions a separate bot writes from the chats you allow: a step you said you'd take, a calendar clash, something worth reading. Off until you switch it on: its button sits beside search either way, and tapping it explains Tidings and sets it up. |
| The strip above search | A one-line summary of what matters across your bots. Off until you switch it on in Settings → Summaries. |
| Your Bots (top of the inbox) | Routines (scheduled jobs), tools and skills, connectors, usage |
| + | A new bot conversation or a group chat with 2 to 6 bots |

Inside a chat:

- **Replies stream in** a word at a time. While a bot works, a short plain phrase says what it's doing, such as "Checking emails against Notion".
- **Cards** are how bots show something structured: a mail draft, a calendar event, a checklist, a question with choices. Tapping a button on a card tells the bot what you decided.
- **Mail drafts are editable.** Change the recipients or text on the card, then Send goes straight to Gmail with exactly what's on screen.
- **Approvals.** When a bot needs permission, a card shows what it wants to do, with Allow and Deny.
- **The tray above the keyboard** holds whatever is still waiting on you in that chat.
- **The waveform button** starts a phone call with the bot, a real conversation described in the next section. The mic dictates into the text box.
- **Where we left off.** Come back to a chat after a while and a card offers a few sentences on where things stand, which you can read or play aloud. Off until you pick a time in Settings → Summaries.
- **Tap the bot's name** for its profile: face, model, skills, routines, what it has learned lately and what it remembers.

Most features that reach outside the app are off to begin with. **Settings → Integrations** has a switch for each.

## Phone calls with your bots

You can call a bot and talk to it the way you'd talk to a person on the phone. This is a real, flowing conversation, not text read back by a synthetic voice: you speak naturally, interrupt mid-sentence, change your mind, and ask what it's doing while it works.

Tap the waveform button in a chat. On iPhone it's a real call, with the system call screen, the Lock Screen, AirPods and the speaker button. On the Mac it uses the Mac's microphone.

You can also start a call without finding the chat first. In Apple's Shortcuts app, add Hermit's **Call Bot** action, pick a bot, and put the shortcut on your Home Screen or give it a name to say to Siri. It opens that bot's chat and starts the call. The phone has to be unlocked.

Hermit also offers spoken phrases of its own, such as "Talk to Family in Hermit". Those haven't been confirmed on a real phone yet, so the shortcut you make yourself is the dependable way. Don't say "call": Siri keeps that word for phone calls of its own kind and answers that Hermit can't be used.

### How a call works

Two things work together on a call, and neither could do it alone.

- **A live voice agent holds the conversation.** It's a speech-to-speech model that listens and talks at the same time, so there's no pause while your words are transcribed and no robotic readback. It answers small things itself.
- **Your bot does the real work.** When you ask for something that needs the bot ("check my inbox", "move Thursday's meeting"), the voice agent decides that by itself and hands the job off. The app starts a normal turn in that bot's own chat, with its own memory, skills and connectors.
- **You're kept company while it works.** You hear quiet typing. Every step the bot takes is passed to the voice agent, so it gives short spoken updates and "what are you doing?" gets a true answer. It never makes up progress.
- **You hear a summary, and the chat keeps everything.** The bot ends with a few sentences written to be spoken, which the voice agent says in its own words. The full reply, with its cards and links, is in the chat when you hang up.
- **You can redirect it.** New instructions steer the running job, and "stop" stops it.

What this means in practice:

|  |  |
| --- | --- |
| Same bot, same lane | A call uses the bot you called. It can hand work to other bots exactly as it does in text. |
| Same history | The call is saved in the chat as a "Voice chat · 4:12" line. Tap it for what each side said, on any device. |
| Sound goes direct | Audio runs straight between your device and the voice service. Your computer only sets the call up. |
| Sign-in stays home | The bridge makes the connection with the sign-in kept on your computer, so the phone never holds it. |
| Two ways to pay | A ChatGPT (Codex) subscription that Hermes is signed in to, or an OpenAI API key at about $0.05 a minute. One never falls back to the other. |
| Voices | Each service has its own set. Pick a default in Settings and a different one per bot in its profile. |
| Limits | 20 minutes a call, 5 jobs a call, 3 running at once |

Not built yet: a bot calling you, and starting a call while the phone is locked. Calls on an API key haven't been tried on a real phone, and how an approval should be presented during a call is still undecided.

## What stays private

Your chats, keys and bot files stay on your computer and your devices. Nothing in the setup is reachable from the public internet: the computer only answers over your own Tailscale network.

What does leave:

- **Model providers** see what your bots send them, as with any use of Hermes.
- **Apple** carries push notifications, which include the first 180 characters of a reply.
- **Google** receives mail and invitations you send from a card.
- **Summaries and Tidings** send the chats you switched on for them to the model you chose for Tidings.

Three habits worth having:

- **Treat pairing codes like passwords.** Whoever pairs can ask your bots to do anything they're able to do.
- **Give each device its own key.** A device paired by code gets one. In **Settings → Connection → Devices** you can see every device and remove one, which is what to do if a phone is lost.
- **Look at From before tapping Send** on a mail card. Your tap is the approval.

## What's rough today

Hermit is a beta built for one owner's setup, so expect edges.

- **Linux is new.** It runs in a test box. No real server, and no Tailscale on Linux, has been tried.
- **Group chats are text only**, and update every few seconds, not word by word.
- **Mail cards send plain text**: no attachments, formatting or signature.
- **A sent meeting invitation can't be changed or cancelled** from its card.
- **Google connectors can't be signed in from the app**, because Google refuses sign-in inside apps. Do those on the computer.
- **Search covers each bot's main chat only**, not groups or side conversations.
- **The Mac app has no Live Activities** and can't send text messages.

Found something else? Send feedback from TestFlight (screenshot, then Share Beta Feedback), with what you tapped and what you expected.

## Words you'll run into

| Word | Meaning |
| --- | --- |
| Hermes | The open-source assistant software on your computer. Hermit talks to it. |
| Bot | One assistant: a Hermes profile with its own memory, tools and face |
| Bot Chat | A bot's one permanent conversation, shared with Hermes's other apps |
| Bridge | Hermit's small background service on your computer. It handles live updates, push, faces and everything Hermes's own API doesn't. |
| Plugin (hermes-cards) | The add-on inside Hermes that lets bots show cards and reports their progress to the bridge |
| Tailscale / tailnet | The private network that joins your devices. Only they can reach the computer. |
| Pairing code | The short one-time code that connects a device |
| Card | A structured block in a chat: a draft, event, checklist or question, with buttons |
| Routine | A job a bot runs on a schedule, such as a morning brief |
| Connector | A link from a bot to an outside service, such as Notion or Linear |
| Tidings | The suggestions feed, written by its own stripped-down bot |
| Helper | A side worker a bot hands part of a job to |
| TestFlight | Apple's app for installing beta versions |
| Hermit Dev | A separate work-in-progress copy of the app, for people building it |
