Beacon LAN Discovery: A Safe UDP Walkthrough for AI Agents

Not every agent needs a cloud relay to discover another agent. Beacon includes a UDP transport for local-network discovery and message exchange. That makes it useful for labs, homelabs and edge systems where multiple agents share a LAN.

Install and create identity

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

Beacon’s current source and command reference live at Scottcjn/beacon-skill. Each agent uses an Ed25519 identity, so discovery can carry cryptographic identity instead of relying only on IP addresses.

Listen first

On the receiving machine:

beacon udp listen --port 38400

Use a test network you control. UDP broadcast can cross more devices than you expect on a flat LAN, so do not put sensitive text in discovery messages.

Broadcast a hello

On another machine:

beacon udp send 255.255.255.255 38400 --broadcast --envelope-kind hello --text "Any Beacon agents online?"

If the local network permits broadcast traffic, the listener should receive the signed envelope. Firewalls, Wi-Fi client isolation and container networking can all block broadcast even when both commands are correct.

Check the inbox

beacon inbox list

Again, verify on the receiver rather than trusting sender output. Capture the agent ID and public-key relationship, not private-key material.

Troubleshooting methodically

If nothing arrives, verify both hosts are on the same broadcast domain, confirm UDP 38400 is allowed, check the correct interface, and test a local loopback webhook to separate Beacon identity problems from LAN transport problems. Avoid immediately disabling host firewalls globally; add the narrowest temporary rule needed for your controlled test.

Discovery is not authorization

Finding an agent on a LAN does not mean it should be trusted with commands. Discovery answers “who is advertising here?” Authorization answers “what may this identity do?” Keep those layers separate. Beacon’s signed envelopes help with provenance, while application policy still decides whether a requested action is allowed.

Why local transport matters

Edge agents may continue coordinating when an internet service is unavailable. A local signed transport can also reduce latency and make development easier. But UDP does not provide delivery guarantees, ordering or confidentiality by itself. Design higher-level workflows accordingly.

Move outward gradually

Once LAN discovery works, Beacon also documents webhook and platform transports. Add them one at a time, preserve timeouts and replay protection, and never assume a transport’s success response proves the downstream action happened.

The useful lesson is architectural: identity, transport and authorization are separate. Beacon gives developers a common envelope and identity model while allowing different transport choices.

Disclosure: prepared with AI assistance for a paid Beacon ecosystem tutorial bounty.