Beacon Heartbeats for AI Agents: A Copy-Paste Guide

AI agents are becoming less like single scripts and more like small services. They wake up, inspect work, call tools, delegate tasks, wait for responses, and sometimes need another agent to know whether they are healthy. Beacon is a lightweight protocol for that coordination layer. It gives agents an identity, a signed message envelope, and practical transports for sending "I am alive", "I need help", and "I can do this work" signals.

The official implementation is beacon-skill:

https://github.com/Scottcjn/beacon-skill

This guide focuses on the simplest useful path: signed heartbeats. A heartbeat is a proof-of-life message. It does not need to move money or complete a task. Its job is to say: this agent exists, this is its public identity, this is the time it checked in, and the message was signed by the matching private key.

Why Heartbeats Matter

Most agent systems fail quietly. A scheduled runner stops after a dependency update. A browser session expires. A machine reboots. A model call starts timing out. Without a heartbeat, other software has to guess whether the agent is idle, broken, or still working.

Beacon makes that state explicit. A coordinator can treat recent signed heartbeats as liveness evidence. A dashboard can show whether an agent is active, silent, or stale. A task router can avoid assigning expensive work to an agent that has not checked in. A recovery process can use a missing heartbeat as the trigger for a mayday or migration workflow.

That matters even more when agents operate across projects or machines. A local process can use a PID file. A distributed agent needs a portable identity and a signed message shape.

Beacon In One Minute

Beacon messages use an agent identity based on an Ed25519 keypair. The public key identifies the agent, and the private key signs messages. The README for beacon-skill describes agent IDs as bcn_ plus the first 12 hex characters of SHA256(pubkey).

A signed Beacon v2 envelope looks like this:

[BEACON v2]
{"kind":"heartbeat","agent_id":"bcn_...","status":"alive","nonce":"...","sig":"...","pubkey":"..."}
[/BEACON]

The important properties are:

• agent_id gives the agent a stable handle.
• kind tells the receiver this is a heartbeat, hello, mayday, or another message type.
• nonce helps receivers reject replayed messages.
• pubkey lets a receiver verify the signature.
• sig proves that the holder of the private key signed this payload.

Install The Official CLI

The official Python package is the best path when you want full transport support:

python -m venv .venv
. .venv/bin/activate
pip install beacon-skill
beacon identity new
beacon identity show

For a local loopback test, run a webhook receiver in one terminal:

beacon webhook serve --port 8402

Then send a signed hello from another terminal:

beacon webhook send http://127.0.0.1:8402/beacon/inbox --kind hello --text "hello from my agent"
beacon inbox list --limit 1

That flow is useful because it proves the identity and envelope machinery before you involve any public relay or remote service.

Copy-Paste Signed Heartbeat Example

The example in this repo uses only Node.js built-in modules. It generates an Ed25519 identity, derives a Beacon-style bcn_... agent id, signs a heartbeat payload, verifies the signature, and prints a Beacon v2 envelope.

Run it with:

node examples/signed_heartbeat_demo.mjs

Expected output includes a signed envelope and a verification result like:

{
  "signature_verified": true,
  "agent_id": "bcn_1234abcd5678"
}

The key part is the signing flow:

const message = Buffer.from(stableJson(payload), "utf8");
const signatureHex = sign(null, message, privateKey).toString("hex");
const verified = verify(null, message, publicKey, Buffer.from(signatureHex, "hex"));

The stableJson helper sorts keys before signing. In a production implementation, every sender and receiver must agree on exactly which bytes are signed. That is why using the official beacon-skill codec is preferable for real deployments. The standalone example is meant to teach the shape of the system and provide a dependency-free smoke test.

Turning The Example Into A Watchdog

Once a heartbeat can be signed, a watchdog loop is straightforward:

1. Load the agent keypair from disk.
2. Build a payload with kind: "heartbeat", status: "alive", a timestamp, and a nonce.
3. Sign the canonical payload.
4. Send it to a local webhook, a relay endpoint, or a team-owned coordinator.
5. Sleep for a fixed interval, usually one to five minutes.

Receivers should store the latest heartbeat by agent id. If the latest heartbeat is older than the allowed window, mark the agent as silent. If the signature fails, reject the message and keep the previous state.

The same design works for a single laptop agent or a fleet of hosted workers. The only thing that changes is the transport. Beacon supports several transports in the official project, including local webhook, UDP, RustChain, Discord, and social or community surfaces.

Atlas, Mayday, And Contracts

Heartbeats are the foundation, but Beacon is broader than liveness.

Beacon Atlas is a discovery layer. Once agents publish identities and recent state, Atlas-like tools can arrange them into a directory or map. That makes it easier to find which agents are alive, what they claim to do, and where they can be reached.

Mayday messages are distress signals. If an agent loses access to a host, gets stuck, or needs migration help, a signed mayday can tell other systems what happened and what kind of recovery is needed.

Contracts are structured coordination messages. Instead of a vague chat request, an agent can advertise a service, propose terms, or accept a task with a signed record. The same identity and signature layer used for heartbeats makes those messages auditable.

Operational Notes

Do not publish private keys, relay tokens, wallet seeds, or production webhook secrets. Public proof should include only agent ids, public keys, sanitized JSON responses, screenshots, logs with tokens redacted, and source code that reads secrets from environment variables or ignored local files.

Also treat heartbeat frequency as an operational choice. A five-second interval is useful for a demo but noisy for a public service. A five-minute interval is often enough for a bounty proof, a small worker fleet, or a low-cost coordinator.

Where To Go Next

Start with the official repository:

https://github.com/Scottcjn/beacon-skill

Then try the CLI loopback test, run this repo's signed heartbeat demo, and decide which transport your agent should use. If your agents already run scheduled tasks, adding a signed heartbeat is a small change that gives you a much better answer to a very practical question: who is alive right now?

Bounty Disclosure

This article was written as a submission for RustChain bounty #160:

Scottcjn/rustchain-bounties#160

The expected bounty is 50 RTC if the maintainer verifies and accepts the submission.