Set up Herald, start to finish.

Three essentials, plus Xcode to build the apps during the beta. A paid Apple Developer account is needed only if you also want phone notifications (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.
• Xcode (free, Mac App Store) — to build the apps during the beta. A free Apple ID works; a paid Apple Developer account ($99/yr) is only needed if you want notifications.

The backend is a small Node server that runs on your Mac and drives Claude for every chat and Job. One command sets it all up.

# clone and run the installer
git clone https://github.com/edbyrne/herald.git
cd herald
./install.sh

The installer checks your prerequisites, generates a secure bearer token, writes your config, installs a launch agent so Herald runs on boot, and finishes by printing the server address + token you'll pair your apps with:

  Server address  http://your-mac.tailnet.ts.net:4123
  Bearer token    3a5b1f39cc38b1bb8c31626b8652ea15…

  ✓ Herald is installed and running. 🤖

The installer already generated this for you and printed it — it's the single password that lets your apps talk to your backend. You'll enter it (with the server address) once in each app when you pair.

# to see it again any time:
grep HERALD_TOKEN herald/.env

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.

During the beta you build the apps yourself in Xcode — a few clicks once Xcode is installed. (Signed, notarised downloads that need no account are coming.)

1. Install Xcode (free, Mac App Store) and the project generator: brew install xcodegen.
2. In herald/ios, run xcodegen, open Herald.xcodeproj, and under Signing & Capabilities choose your own Apple ID / team for both targets.
3. Run the Herald scheme to your iPhone, and the HeraldMac scheme for the desktop app.

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.