Herald — Install Guide

What we'll cover

What you'll need
Get the apps
Set up your Mac
Sign in
Link your Mac
Notifications
Give it email (optional)
Create & manage Jobs

What you'll need

Two essentials — that's it. The apps just download, and your phone reaches your Mac through Herald's hosted relay, so there's no VPN to set up and nothing exposed to the public internet.

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 (claude login).

✓

Already use Claude Code on this Mac? Then you're most of the way there — Herald just points at the claude you already have.

🔒

Your conversations are end-to-end encrypted between your own devices. The relay only passes ciphertext through — it can't read your messages, and Claude still runs on your Mac on your own subscription.

Get the apps

All ready-to-run and signed — no Xcode, no developer account.

iPhone: install via TestFlight — free, just needs an Apple ID. (If TestFlight says the build is in review, give it a little while — Apple reviews the first beta build.)
Mac — Herald Host: download Herald Host (notarised .dmg), drag it to Applications, and open it. It lives in your menu bar and sets up + runs the backend for you (next step).
Mac — optional chat app: download the Herald Mac app to chat from your desktop too — same account, same chats.

Set up your Mac

Open Herald Host from your menu bar and click Set up Herald. It installs the backend — the small Node server that drives Claude for every chat and Job — and starts it, running quietly in the background and on every boot. No Terminal.

⚠

Needs Node + Claude Code. The backend runs on Node 22+ and drives the claude CLI you've signed into (claude login). If Node is missing, Herald Host gives you a one-click link to install it. And don't set ANTHROPIC_API_KEY — Herald refuses to start with it, to keep billing on your Claude subscription rather than a metered API key.

Prefer the command line?

If you have access to the source, you can set the backend up from a terminal instead — same result, then carry on to the next step:

git clone https://github.com/edbyrne/herald.git
cd herald
./install.sh

Sign in

Open the Herald app on your iPhone and tap Sign in with Apple. That's your whole account — no passwords, no server address to type in. Sign in with the same Apple ID on any device and you land on the same account.

✓

Behind the scenes this creates your encryption keys on the device and registers you with the relay. Your private keys never leave your phone.

Link your Mac

One short code ties your Mac's backend to your account:

On your iPhone: Settings → Link a Mac → Generate a code (good for 10 minutes).
On your Mac: open the Herald Host menu-bar app — or visit http://127.0.0.1:4123/setup.html — and paste the code.
Tap Link this Mac. The menu-bar icon turns to a checkmark once it's connected to the relay.

Now send a first message from your phone — “hello, are you there?” — and watch the reply stream in. That's your agent, running on your Mac, answering on your phone, from anywhere.

✓

Adding another device later — an iPad, a second phone? Sign in with the same Apple ID, or use Settings → Link a device with a code. Everything stays in sync over the relay.

Notifications

Push just works. When a Job finishes or a reply lands, the relay sends a notification straight to your phone — the first time the app asks, allow notifications. Nothing to build, no Apple Developer account.

They're off by default per Job, so Jobs stay quiet until you want them. Turn notifications on for any individual Job and you'll get a push when it finishes.

🔒

A push only ever says that something happened (e.g. “New reply”) plus a badge count — never your message content. The relay can't read your messages.

Give it email

Optional

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
[email protected]
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:

Email a summary of today's Portfolio Watch to me at the end of each run.

When my accountant replies to that thread, draft an answer and send it.

🔒

Herald only acts on mail it can verify is genuinely from you, so a stranger emailing the address can't issue it commands.

Create & manage Jobs

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

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

Every weekday at 7am, summarise my unread email, today's calendar and any overnight Slack DMs into one short briefing.

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.

✓

Change your mind later? Just tell it: “run this on Sundays instead,” or “also include my GitHub notifications.” It updates the Job itself.

That's it — you have an agent.

Leave the Mac running. Tomorrow morning, the work will already be done.