# Set up Hark (steps for Hermes Agent) You are a Hermes agent. Your user wants to talk to you from Hark, an iPhone voice app. Hark needs three things from this machine, and you will hand them over as one link: ``` hark://connect?url=&key=&relay= ``` Work through the steps in order. Check each result before moving on, and keep the user's work to a minimum: only ask them for something you cannot do yourself. Never print a key anywhere except the final link. ## 1. Turn on the API server Hark talks to your gateway's OpenAI-compatible API server. 1. Run `hermes config env-path` and read that `.env` file. If `API_SERVER_ENABLED=true` and `API_SERVER_KEY` are already set, reuse them and skip to the check below. 2. Otherwise generate a key with `openssl rand -hex 32`, then run `hermes config set API_SERVER_ENABLED true` and `hermes config set API_SERVER_KEY `. Leave `API_SERVER_HOST` unset (it stays on 127.0.0.1; step 2 publishes it safely). 3. Restart the gateway: `hermes gateway restart`. If that is refused because you are running inside the gateway, ask the user to send `/restart` in this chat, and continue once they say it is done. Check: `curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer " http://127.0.0.1:8642/v1/capabilities` prints `200` (use `API_SERVER_PORT` instead of 8642 if it is set). ## 2. Give it an HTTPS address The phone needs HTTPS. Use Tailscale. 1. Run `tailscale status`. If Tailscale is not installed or not logged in, ask the user to install it on this machine and on their iPhone (https://tailscale.com/download), sign in to the same account on both, and tell you when done. 2. Run `tailscale serve --bg --https=443 http://127.0.0.1:8642`. If it says HTTPS is not enabled, send the user the link it prints (or https://login.tailscale.com/admin/dns) to turn on MagicDNS and HTTPS certificates, then run it again. 3. The URL is `https://` plus this machine's DNS name: `tailscale status --json` → `Self.DNSName`, without the trailing dot. 4. Ask the user whether their iPhone has Tailscale. Only if it doesn't, use `tailscale funnel --bg --https=443 http://127.0.0.1:8642` instead, and tell them this makes the gateway reachable from the internet, protected only by its key. Do not use a Cloudflare quick tunnel (trycloudflare.com): it cannot stream replies, so Hark would not work. Never bind the API server to 0.0.0.0 or open port 8642 in a firewall. Check: `curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer " /v1/capabilities` prints `200`. ## 3. Get a ModelRelay API key ModelRelay turns speech into text and replies into speech for Hark. It does not replace your model provider: leave Hermes' model and provider settings (OpenRouter, Anthropic, …) exactly as they are. Keys start with `mr_sk_`. 1. If this machine already has a key (`MODELRELAY_API_KEY` in the environment, or ModelRelay as your provider), use it. Never ask the user to paste a key. 2. Otherwise install the CLI if `mrl` is missing. With Homebrew (macOS or Linux): `brew install tensor-systems/tap/mrl`. Without it, on Linux (or Windows under WSL), download the newest release into `~/.local/bin`: ``` V=$(git ls-remote --tags --sort=-v:refname https://github.com/tensor-systems/mrl 'v*' | head -1 | sed 's#.*refs/tags/v##; s#\^{}##') ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/') mkdir -p ~/.local/bin curl -fsSL "https://releases.modelrelay.ai/mrl/$V/mrl-$V-linux-$ARCH.tar.gz" | tar -xz -C ~/.local/bin mrl ``` If `~/.local/bin` isn't on `PATH`, run it as `~/.local/bin/mrl`. 3. Sign the user in to ModelRelay (a new account is created if they have none; it comes with free credit). Ask whether they are at this computer, where a browser can open. - **At this computer:** run `mrl auth login --web`. It opens the browser here to sign in or sign up. - **Not here** (chatting from their phone, or this machine has no screen): start `mrl auth login --device` as a background process (it keeps running until they approve), read its first lines, and send them the link it prints, on its own line. They tap it on their phone, sign in (or sign up), and approve; `mrl` then saves the login and exits. Wait for it to exit before step 4. Never send the `--web` link: it only completes on this machine. If `mrl` has no `--device` option, it is older than 5.4: upgrade it as in step 2. 4. Run `mrl keys create --name hark --print` and keep its output (the key, and nothing else). If `mrl` says it has no `keys` command, it is older than 5.3: upgrade it (`brew upgrade mrl`, or download again as above) and retry. Check (costs a fraction of a cent): ``` curl -s -o /dev/null -w '%{http_code}\n' https://api.modelrelay.ai/v1/audio/speech \ -H "Authorization: Bearer " -H "Content-Type: application/json" \ -d '{"model":"gemini-3.8-flash-tts","input":"ok","voice":"Kore","response_format":"wav"}' ``` `200` is good. `401` means the key is wrong. `402` means the account has no credit: send the user to https://modelrelay.ai to add some. ## 4. Hand over the link Build the link, percent-encoding each value: ``` python3 -c 'import sys, urllib.parse as u; print("hark://connect?" + u.urlencode({"url": sys.argv[1], "key": sys.argv[2], "relay": sys.argv[3]}))' ``` - If the user is chatting with you in a terminal, also show it as a QR code they can scan with the iPhone Camera: `qrencode -t ansiutf8 ''`, or `python3 -m pip install --user qrcode && python3 -m qrcode ''`. - If they are chatting from their iPhone (Telegram, Discord, …), send the link on its own line: tapping it opens Hark. Suggest they delete that message once Hark connects, since it contains the gateway key. Hark asks the user to confirm the gateway, then connects. If it shows an error, the setup page lists fixes: https://heyhark.app/setup