Operate the relay

This page covers everything you do with a relay after it is set up: update it, change its settings, use it from several Macs, run one you deployed yourself, and delete it. It ends with the full troubleshooting table. It is for the person who owns the relay. To set one up, see Cloud relay.

Everything here is under Settings > Cloud, mostly in the Advanced section at the bottom of the tab.

Show the whole capture

Advanced shows every setting of the relay, with the action buttons below the fields.

Update the relay#

Each version of Herald carries the relay program that matches it. When the relay that is running differs from the one inside your Herald, the Relay section says that a newer relay is bundled and shows an Update the relay button.

Press it. Herald uploads the new program over the old one. The relay keeps its name, its address, its data and its secrets, so this Mac stays paired and every agent key and connector keeps working.

Redeploy under Advanced does the same thing at any time.

Advanced settings#

Every field is visible and editable. Change a value and press Apply settings. A value that lives in the relay program, such as a limit, makes Herald redeploy the relay.

The buttons below the fields:

The same settings are available to scripts through PUT /v1/relay/settings.

Several Macs#

One relay can serve several Macs, five by default. Each Mac has its own mailbox, its own keys and its own limits. Set the relay up on the first Mac, then on each other Mac enter the same Relay URL and Pairing secret under Advanced and press Pair with a code.

Advanced > Devices on this relay lists every Mac with its name, whether it is connected or when it was last seen, and which one is this Mac.

How an agent reaches the right Mac:

• A key belongs to the Mac that created it, so a key always reaches that Mac.
• A connector that signs in is offered the Mac that is connected right now, or else the one seen most recently. The approval page names the Mac and links to the others.

The relay keeps the list clean by itself:

• A Mac that pairs again under the same name replaces its old entry, and the old mailbox is wiped.
• Unpairing removes the Mac's entry and wipes its mailbox.
• An entry is dropped when its credentials fail to verify, its mailbox is gone, or it has not connected for 30 days.

Remove beside an entry is offered only for an entry this Mac may remove: one with the same name as this Mac, one whose credentials fail to verify, or one that has not connected for a week. A different Mac that is in use can never be removed from another Mac.

Delete the relay#

Advanced > Delete relay from Cloudflare… asks for confirmation and then removes the relay from your Cloudflare account, with every mailbox, key and waiting notification.

The storage bucket is deleted only when it is empty. Cloudflare refuses to delete a bucket that still holds voice replies, and Herald says so. A custom domain's DNS record and rules stay in your Cloudflare account.

To stop using the relay without deleting it, turn Enable relay off instead. See Turn the relay off.

Run your own relay#

Herald's deploy is a convenience. Any relay that speaks the same protocol works: enter its address in Advanced > Relay URL and press Pair with a code.

To deploy the same relay program yourself with Cloudflare's wrangler tool, from the Herald repository:

cd relay
npm install
npm test
wrangler secret put RELAY_SECRET
wrangler secret put PAIRING_SECRET
npm run r2:setup
npm run deploy

For local development, wrangler dev needs a file relay/.dev.vars that sets RELAY_SECRET.

Limits are set with variables on the relay program. Their names are in the relay API. To restrict where reply events may be delivered, set EVENT_CALLBACK_HOSTS to a comma-separated list of host names.

If you write your own implementation, the folder conformance/ in the repository is a test suite that checks any relay from the outside:

RELAY_URL="https://herald-relay.example.workers.dev" npm test -w conformance

What Herald does in your Cloudflare account#

Herald calls Cloudflare's API only when you deploy, change a relay setting or delete the relay. These are all the calls it makes, so that you can check them against the token's permissions.

After a deploy, Herald asks the relay's own /health address until it answers.

If it does not work#

Related#

• How the relay works: the design, the credentials and the limits.
• Use a custom domain: give the relay an address you own.
• Cloud relay API (local): every operation on this page, for scripts.
• MCP relay tools: the same, for a local agent.