Getting started
Set up Hervi in about half an hour. Run Hermes on a computer you own and invite everyone with a code. The Hervi plugin is optional and adds phone tools and notifications.
Hervi is the iPhone app. The assistant itself is Hermes Agent, the free, open-source assistant from Nous Research, running on a computer you own. One person sets it up once; everyone else just scans a code.
What you need
- A computer that stays on. A Linux PC, a home server or NAS, a small cloud server, or a Mac. No Mac is required, and it can run in Docker or Kubernetes.
- Hermes Agent 0.22.5 or later, before 0.24. Check with
hermes --version. - A way for phones to reach it. This guide uses Tailscale, one way among several: it runs on that computer and on every iPhone, all in your tailnet, with MagicDNS and HTTPS Certificates turned on in Tailscale’s admin console. Keep Funnel off. Cloudflare Access, oauth2-proxy and Hermes’s own sign-in work too.
- A model. An API key from a provider you choose, or a model running on your own hardware.
- An iPhone with iOS 26 or later for each person, with Hervi on it. For now Hervi comes through TestFlight; it’s coming to the App Store.
1. Install Hermes
Follow the Hermes Agent install guide, then check it:
hermes --version
2. Give Hervi its own Hermes home
Run Hervi’s assistant in a Hermes home of its own, next to any you already use, with no messaging gateway on it. That keeps chats working (a gateway on the same home can refuse or take over the app’s chats), and it keeps everyone’s profiles apart from your own.
export HERVI_HOME="$HOME/.hermes-hervi"
mkdir -p "$HERVI_HOME/profiles" "$HERVI_HOME/logs" "$HERVI_HOME/locks"
chmod 700 "$HERVI_HOME"
Never run Hermes’s chat, terminal app or hermes gateway against this home. Edit its files with a text editor and
restart the dashboard instead.
3. A profile for each person
Every person, you included, gets a profile: a folder under $HERVI_HOME/profiles, named with lowercase letters,
digits, - and _. Each phone is paired to exactly one profile, so memory, chats and permissions stay separate.
P="$HERVI_HOME/profiles/family-anna"
mkdir -p "$P" && chmod 700 "$P"
Write $P/config.yaml. This is the shape Hervi is tested with: manual approvals, so anything that needs an OK
waits for the person, and a short list of tools, so the assistant can answer, remember and plan but can’t run
commands, read files or browse.
model:
default: z-ai/glm-5.3-flash # the model this person talks to
provider: openrouter
auxiliary:
title_generation:
enabled: true # chats get real titles
approvals:
mode: manual # never "off" or "smart"
timeout: 300 # the app's card says "I'll wait 5 minutes."
platform_toolsets:
# What the assistant may use. hervi_phone is the plugin's phone tools (step 4).
cli: [clarify, memory, session_search, todo, hervi_phone]
agent:
clarify_timeout: 3600 # an hour to answer a question, so people can answer later
# Every other toolset off, so nothing added later reaches the model.
disabled_toolsets: [bot_room, browser, catalog, code_execution, coding, computer_use, connections, context_engine,
cronjob, debugging, delegation, desktop_ui, discord, discord_admin, feishu_doc, feishu_drive, file, image_gen,
kanban, onboarding, project, safe, search, skills, terminal, tts, video, video_gen, vision, web, x_search, yuanbao]
onboarding:
profile_build: "off"
security:
allow_lazy_installs: false # never install packages on anyone's behalf
updates:
check: false
Put the provider’s key in $P/.env (for OpenRouter, OPENROUTER_API_KEY=…), and the assistant’s voice in
$P/SOUL.md. Hervi calls the assistant by your skin’s branding.agent_name (display.skin); Hermes’s built-in skins
read as “Hermes”. To give someone more (a calendar service or the lights, say), add that toolset to cli, take it out of
disabled_toolsets, and restart the dashboard. Approvals stay manual.
4. Add the Hervi plugin (optional)
Hervi works without it: chats, photos, approvals and invites need only Hermes. The plugin adds two things. The assistant can use each person’s iPhone (Reminders, Calendar, Apple Weather and Location, and Apple Health if you turn it on, always after they tap Allow), and it can send notifications when Hervi is closed. Without the plugin, Hervi shows those two in Settings as not on the home computer yet. To add it, install it into each profile, then enable it:
export HERMES_HOME="$HERVI_HOME" HERMES_GATEWAY_LOCK_DIR="$HERVI_HOME/locks"
hermes -p family-anna plugins install https://github.com/dillonbrowne/hervi-plugin --no-enable
hermes -p family-anna plugins enable hervi
Add --ref <commit> to the install to pin a version. Restart the dashboard (step 6) after installing or updating
the plugin, then check it:
hermes -p family-anna hervi status
Apple Health is off unless you turn it on, per profile, in that profile’s config.yaml. Turn it on only for a profile
one person uses: a second phone on it would get the same card and could answer with its own Health. The answers stay
in the chat for whoever runs the computer to read.
plugins:
entries:
hervi:
settings:
health: true
hervi status prints no secrets and changes nothing. It ends with “Ready” when phone tools will work for that
profile.
5. Sign-in
Hervi signs in through the dashboard’s basic sign-in: one household username and password. You type the password once, on your own phone, and no phone ever stores it. Phones keep only sign-in tokens.
Make a password hash with Hermes’s own helper. Run it from your Hermes checkout (the official installer puts it
in ~/.hermes/hermes-agent) with the Python Hermes runs on, which head -1 "$(command -v hermes)" shows after the
#!:
cd ~/.hermes/hermes-agent
HERMES_PY="$(head -1 "$(command -v hermes)" | sed 's/^#!//')"
printf 'Household password: '; stty -echo; read -r HERVI_PW; stty echo; echo
HASH="$(HERVI_PW="$HERVI_PW" "$HERMES_PY" -c 'import os; from plugins.dashboard_auth.basic import hash_password; print(hash_password(os.environ["HERVI_PW"]))')"
unset HERVI_PW
Then write Hervi’s home’s .env:
( umask 077; cat > "$HERVI_HOME/.env" <<EOF
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=household
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH=$HASH
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 48)
EOF
)
The secret signs every token: keep it, or every restart signs every phone out.
6. Run the dashboard
Hervi talks to Hermes’s dashboard, hermes serve, listening on this computer only. Tailscale brings the phones to it.
export HERMES_HOME="$HERVI_HOME" HERMES_GATEWAY_LOCK_DIR="$HERVI_HOME/locks"
export HERMES_DASHBOARD_PUBLIC_URL="https://your-computer.your-tailnet.ts.net"
hermes serve --host 127.0.0.1 --port 9119 --skip-build
HERMES_DASHBOARD_PUBLIC_URL turns sign-in on and must be exactly the address the phones use: https:// plus the
computer’s MagicDNS name, with no port and no slash. Run it as a service so it starts with the computer: launchd on a
Mac, systemd on Linux, or a container (Docker and Kubernetes).
7. Reach it with Tailscale
This is one way to reach it. Prefer a different front door? Hervi works with those too.
tailscale serve --bg 9119
That gives the dashboard a real certificate at https://your-computer.your-tailnet.ts.net, reachable only inside
your tailnet. Check it:
curl -s http://127.0.0.1:9119/api/health
# {"ok": true, "version": "…", "auth_required": true}
"auth_required": false means the public URL isn’t set, so sign-in is off. Fix that before going on.
8. Set up your own phone
- With Tailscale, turn it on first. Open Hervi, tap Get started, then Set up manually.
- Enter the address (
your-computer.your-tailnet.ts.net), the username and password from step 5, your own profile and a home name. The assistant’s name is optional: left empty, Hervi uses the name your Hermes gives it, and follows it when it changes. - Hervi checks that it can find your assistant, sign in and say hello. Then it asks what to call you.
9. Invite everyone else
- Make their profile first (step 3), install the plugin into it if you use it (step 4), and restart the dashboard.
- On your phone, turn on Settings › Advanced › Let this iPhone invite others. It’s off for a newly paired phone; a phone paired before the update keeps what it had.
- Then Settings › Advanced › Invite someone. Enter their first name; Hervi suggests the profile from it and checks your Face ID.
- Hervi shows an invite code for two minutes. On their iPhone (with Tailscale on, if that’s how you reach home), open Hervi, tap Get started, then Scan invite code. The scanner also reads a code from a picture in Photos.
That’s it: no address and no password on their phone. To let Hervi notify them when it’s closed, see Notifications.