Set up Herald, start to finish.

Three essentials — that's it. The Herald apps just download; you only need the last two if you want push notifications on your phone (covered in step 7).

• A Mac that stays on — any Apple-silicon Mac. A second-hand Mac mini is perfect: silent, low-power, set-and-forget.
• A Claude subscription (Pro or Max) with the claude CLI installed and logged in.
• Tailscale — free for personal use, on your Mac and your phone.
• For notifications only — Xcode (free) and a paid Apple Developer account ($99/yr), to build the open-source Herald Notify app with your own keys. Skip both if you don't need phone push.

The backend is a small Node server that runs on your Mac and drives Claude for every chat and Job. Grab the code, install dependencies, and create your config file.

# clone and enter the project
git clone https://github.com/edbyrne/herald.git
cd herald

# install dependencies
npm install

# create your config from the template
cp .env.example .env

Open .env and set two things: your bearer token (next step) and HERALD_BIND=0.0.0.0 so your phone can reach it over Tailscale. Then start it:

# run it (stays in the foreground for now)
npm start

✓ Herald listening on :4123

cp launchd/me.edbyrne.herald.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/me.edbyrne.herald.plist

The bearer token is the single password that lets your apps talk to your backend. Nothing reaches Herald without it. Generate a long random one:

# generates a strong 64-character token
openssl rand -hex 32

9f2c…a1b7  ← copy this

Paste it into .env as HERALD_TOKEN=…. You'll enter the same token once in each app when you pair. Treat it like a password.

Tailscale creates a private, encrypted network just between your devices — so your phone can reach your Mac from anywhere without opening any ports or exposing anything to the public internet.

1. Install Tailscale on your Mac from tailscale.com/download and sign in.
2. Install the Tailscale app on your iPhone and sign in with the same account.
3. On the Mac, note its Tailscale name — something like your-mac.tailnet-name.ts.net (or its 100.x.x.x address).

That hostname plus the port — http://your-mac.tailnet.ts.net:4123 — is the address your apps will use.

The Herald Mac and iPhone apps are ready-to-install builds — no Xcode, no developer account, nothing to compile.

• Mac: download the Herald Mac app (a signed, notarised .dmg), drag it into Applications, and open it.
• iPhone: install Herald from TestFlight — a free Apple ID is all that's needed.

Open the app for the first time and it'll ask for two things:

• Server address — the Tailscale URL from step 4, e.g. http://your-mac.tailnet.ts.net:4123
• Bearer token — the one you generated in step 3

Tap connect. You should see your (empty) chat list. Send a first message — “hello, are you there?” — and watch the reply stream in. That's your agent, running on your Mac, answering on your phone.

Herald keeps notifications sovereign: there is no notification server in the middle that anyone — us included — could read. The trade-off is that to get push on your phone you build one tiny open-source companion app, Herald Notify, signed with your Apple account and your push key. Notifications then travel your Mac → Apple → your phone, and no one else is ever in the loop.

Skip this entirely if you don't need phone push — chat and Jobs work fully without it, and the Mac app shows its own notifications while it's running.

What it is

A small receiver app. When a Job finishes or a reply lands, your backend sends a push straight to it; tapping the notification opens the main Herald app to the right place. It stays out of the way otherwise.

One-time setup

1. Join the Apple Developer Program ($99/yr) — push keys require a paid account.
2. Open the open-source Herald Notify project in Xcode, set it to your own team, and run it onto your iPhone.
3. In your developer account, create an APNs key (a .p8 file); note its Key ID and your Team ID.
4. Hand those to your backend so Herald can push with your key:

   # ~/.herald-secrets/apns.env  (+ the AuthKey_*.p8 file alongside)
   APNS_KEY_ID=<your-key-id>
   APNS_TEAM_ID=<your-team-id>
   APNS_BUNDLE_ID=<your-notify-bundle-id>

5. Open Herald Notify, point it at your backend (the same address + token as the main app), and it registers itself. Notifications now flow — privately.

This is one of Herald's best tricks: give it an email address of its own and it can send, receive and reply to real email on its own — something Claude by itself can't do. Reply to a thread from any mail app and Herald acts on it and writes back.

What you'll need

• A dedicated email account for Herald — a fresh Gmail is easiest. Don't use your personal inbox.
• Turn on 2-factor authentication on that account, then create an app password (Google → Security → App passwords). This is a 16-character key that lets Herald sign in safely.

Where the credentials go

Herald keeps email secrets outside the app folder, in a protected file on your Mac:

mkdir -p ~/.herald-secrets
# put these two lines in ~/.herald-secrets/email.env
GMAIL_ADDRESS=herald.yourname@gmail.com
GMAIL_APP_PASSWORD=<paste-the-16-char-app-password>

Restart Herald and it'll start watching that inbox. Every authenticated email from you becomes an instruction it acts on.

How you'll use it

Just email it, or ask it to handle mail in chat:

Jobs are recurring chats that run on a schedule. The clever part: you don't fill in forms — you just tell Herald what you want in plain English, and it sets the schedule, the prompt and the tools for you.

Make one

1. Switch to the Jobs tab and tap ＋. Give it a name (e.g. “Morning Briefing”).
2. Open its chat and describe it:

Herald confirms the schedule and switches the Job on. From then on it runs itself.

Manage them

• Enable / Pause — toggle a Job on or off any time.
• Run now — fire it immediately to test it, without waiting for the schedule.
• Last run — every Job shows when it last ran and whether it succeeded; tap into its chat to read the full result.
• Notifications — off by default, so Jobs stay quiet. Turn it on per-Job if you want a push when one finishes.