---
title: "Getting started"
description: "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."
url: https://www.hervi.app/docs/getting-started/
---

# Getting started

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](/docs/docker-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](https://github.com/NousResearch/hermes-agent), then check it:

```sh
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.

```sh
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.

```sh
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.

```yaml
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:

```sh
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:

```sh
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.

```yaml
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
`#!`:

```sh
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`:

```sh
( 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.

```sh
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](/docs/docker-kubernetes/)).

## 7. Reach it with Tailscale

This is one way to reach it. Prefer a different front door? Hervi works with those too.

```sh
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:

```sh
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

1. With Tailscale, turn it on first. Open Hervi, tap **Get started**, then **Set up manually**.
2. 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.
3. Hervi checks that it can find your assistant, sign in and say hello. Then it asks what to call you.

## 9. Invite everyone else

1. Make their profile first (step 3), install the plugin into it if you use it (step 4), and restart the dashboard.
2. 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.
3. Then **Settings › Advanced › Invite someone**. Enter their first name; Hervi suggests the profile
   from it and checks your Face ID.
4. 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](/docs/notifications/).
