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. Install both, then connect the app.

The app has a short version of this guide: tap New to Hermes? on the first screen, or go to Settings → Quick start. Prefer to plan it with your own assistant? Hand this guide to Claude.

On this page

  1. What Hermit is
  2. From a first chore to a team
  3. Ask your own Claude
  4. How the pieces fit
  5. Look before you set anything up
  6. What you need
  7. Setup, step by step
  8. A tour of the app
  9. Phone calls with your bots
  10. What stays private
  11. What's rough today
  12. Words you'll run into

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, 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. A chat app can only tell you what to type.

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:

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:

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

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.

BotIts lane
Running the day
Chief of StaffSorts the inbox, drafts email for approval (never sends by itself), manages the calendar, sends a morning brief
Product
Product ManagementRoadmap, backlog and what's worth building
Product OwnerThe front door to the coding agents: takes a request and hands the build work on
AgitatorRaises one pointed product question each weekday
Engineering
DevOpsBuilds and releases, reliability and cost
ComplianceKeeps checking the code and cloud setup against regulatory requirements
Business
CFOThe company's finances
Investor RelationsThe investor pipeline and those relationships
Sales LeadThe sales pipeline
MarketingOutbound marketing
SocialDrafts social posts
The system itself
Hermes SysadminLooks after the Hermes installation and the other bots
Home
FamilyHousehold logistics
FitnessPersonal 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. Every quoted line is a prompt: copy it into a bot's chat as it stands, or change the details to fit.

LEVEL 1

Hand it a chore

One-off jobs on your own computer, done rather than explained.

Your filesCommands

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

Routines that run on time, whether or not you remember.

SchedulesMailCalendar

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

It checks for you and stays quiet until something changes.

SchedulesThe web

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

It does the next step itself and asks before anything you'd want to see first.

ConnectorsApprovals

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

Several steps that run end to end, with little to no input from you.

SchedulesConnectorsCommandsThe web

Sales: meeting briefs

Walk into every meeting already knowing the room.

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

Product: research to requirements

Turn what the market is saying into work your team can pick up.

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

DevOps: always on call

Fix the routine problems itself, and wake you only for the rest.

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

Run a team

A few bots with their own jobs and memory, handing work to each other.

Several botsEverything above

This is the bot-first setup described above. 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 the guide together with the first button below. If your assistant can browse the web, the second button copies the prompt with this page's address instead.

  2. Start a new chat in Claude, or any assistant you like, and paste.

  3. Answer its questions.

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. The guide is also available as plain text.

How the pieces fit

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

The app talks only to your own computer Your devices Each device pairs once with a short code Hermit app iPhone, iPad or Mac Inbox, chats, cards Your computer, always on Hermes Agent Your bots: memory, tools, routines Its cards plugin reports progress to the bridge Bridge Live updates, push, faces, summaries Sends the mail and invites you approve Apple push service Google mail and calendar over Tailscale, private to you live updates alerts notifications mail you send from a card
Swipe sideways to see all of it.

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).

  2. 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 needWhyNotes
A computer that stays onHermes and your bots run thereA Mac is the tested path. Linux with systemd works in a test box, and no real server has tried it yet.
Hermes AgentIt is the assistantInstalled in ~/.hermes, with at least one bot you can already chat with
TailscaleThe private connection between themOn the computer and on each device. Free for personal use. Sign in to the same account on both.
An iPhone, iPad or MacTo run HermitiOS 18 or later. 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

  2. Hermes. On the computer, open Terminal and run this. It walks you through picking a model, from Claude or GPT with your own key to a free one running on the Mac.

Once you can chat with Hermes in Terminal, go on to Setup. The Hermes documentation covers the rest.

Optional, each for one feature:

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.
    • Mac: download the latest disk image from the hermit-bridge releases page and drag Hermit to Applications. It updates itself after that.
  2. Install Hermit's helper on the computer. The easy way: tap Copy Setup Prompt on Hermit's first screen and send it to a Hermes bot you already talk to. It installs the plugin, runs setup, and replies with the address and code for step 3. Or do it yourself in Terminal on the computer that runs Hermes:

    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.

  3. Pair. Open Hermit and enter the address and the code on the first screen, or copy the whole reply and tap Paste. The code works once and expires in 10 minutes. If it lapses, run hermes hermit setup again for a new one.

  4. 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.

  5. Say hello. Open a bot from the inbox and send a message. The reply should appear a word at a time.

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 seeWhat to check
Can't reach HermesTailscale is on and signed in on the phone and the computer
Replies arrive all at onceSettings → Connection → Live updates is Off, so the bridge isn't running. Run setup again.
Brief errors across the appHermes is restarting. It's back in about 20 seconds.
No notificationsPush needs the Apple key. Everything else works without it.

The hermit-bridge README has the longer troubleshooting list, and Support has a way to reach us.

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.

WhereWhat it's for
A bot's rowOpens its chat. The row says "Working" while it's busy, and "Needs your OK" or "Draft ready" when it wants you.
Pinned facesYour most-used bots, at the top. A ring means working, a red ring means it needs you.
SearchFinds bots, and messages inside every bot's chat
Waiting on YouEvery question, approval and draft from every bot, answerable in one place
TidingsA 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, and tapping it explains Tidings and sets it up.
The strip above searchA one-line summary of what matters across your bots. Off until you switch it on in Settings → Summaries.
Your BotsAt the 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:

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 talks while your bot does the work You Speaking naturally Live voice agent Talks with you; you can interrupt Decides when a request needs the bot Hermit app Runs the call, plays quiet typing while it waits Bridge Sets up the call; keeps the sign-in off the phone Your bot Does the work in its own chat, with its own tools live audio hands the job off progress, then the summary sets up the call job out, steps back a turn in the bot's chat
Swipe sideways to see all of it.

What this means in practice:

Same bot, same laneA call uses the bot you called. It can hand work to other bots exactly as it does in text.
Same historyThe 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 directAudio runs straight between your device and the voice service. Your computer only sets the call up.
Sign-in stays homeThe bridge makes the connection with the sign-in kept on your computer, so the phone never holds it.
Two ways to payA 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.
VoicesEach service has its own set. Pick a default in Settings and a different one per bot in its profile.
Limits20 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. The privacy policy has the details.

What does leave:

Three habits worth having:

What's rough today

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

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

Words you'll run into

WordMeaning
HermesThe open-source assistant software on your computer. Hermit talks to it.
BotOne assistant: a Hermes profile with its own memory, tools and face
Bot ChatA bot's one permanent conversation, shared with Hermes's other apps
BridgeHermit's small background service on your computer. It handles live updates, push, faces and everything Hermes's own API doesn't.
PluginThe add-on inside Hermes (hermes-cards) that lets bots show cards and reports their progress to the bridge
TailscaleThe private network (your tailnet) that joins your devices. Only they can reach the computer.
Pairing codeThe short one-time code that connects a device
CardA structured block in a chat: a draft, event, checklist or question, with buttons
RoutineA job a bot runs on a schedule, such as a morning brief
ConnectorA link from a bot to an outside service, such as Notion or Linear
TidingsThe suggestions feed, written by its own stripped-down bot
HelperA side worker a bot hands part of a job to
TestFlightApple's app for installing beta versions