The beacon node mainly comprises of 2 programs:

  • Internal beacon
  • External beacon


The internal and external beacons share the same executable which is built as part of OpenWeaver. See the README for build instructions.


$ ./beacon/beacon --help


    -d, --discovery-addr <discovery_addr>
    -h, --heartbeat-addr <heartbeat_addr>
    -b, --beacon-addr <beacon_addr>
    -h, --help <help>
    -v, --version <version>

The beacon executable supports two optional command-line arguments to set the discovery and heartbeat listener addresses. The discovery address enables nodes to discover the nodes in its registry and the heartbeat address enables nodes to add themselves to the registry.

By default, discovery_addr is set to and heartbeat_addr is set to This means that the beacon node can only be reached from localhost, i.e. it is secure by default.

To make it available for other nodes not on localhost, it needs to listen on external interfaces as well using to bind to all interfaces:

$ ./beacon/beacon --discovery_addr "" --heartbeat_addr ""

In addition, the beacon node supports a --beacon_addr parameter to register the cluster with the wider Marlin Relay.


To set up the beacon node, run the beacon executable twice with different arguments:

# External beacon
$ ./beacon/beacon --discovery_addr "" --heartbeat_addr "" --beacon_addr "<beacon_address>"
# Internal beacon
$ ./beacon/beacon --discovery_addr "" --heartbeat_addr ""

Why two beacons?

While users communicate with relay nodes using their public IPs, most cluster setups would be using relay nodes which can communicate with each other through private networks and internal IPs as well. These private networks are usually more performant as well as relatively cheaper, hence the need to prefer this for internal traffic.

The internal beacon contains the private IPs of the relay nodes which they can use for internal discovery while the external beacon contains public IPs of the relays which users can use for external discovery. This way, all parties get an optimal choice of networking for their connections.

Security considerations

Expose for public access

  • Discovery address of external beacon
  • Discovery address of internal beacon

While the discovery address of the internal beacon is safe for public access, they usually don't gain anything from knowing internal IPs. On the flip side, details about the network (like topology, internal addresses, hidden internal-only nodes, etc) might be leaked through this. Hence, it's better to not expose this as a defense in depth measure.

Protect from public access

  • Heartbeat address of internal beacon
  • Heartbeat address of external beacon

If the public gains access to the heartbeat addresses, then they have the ability to poison the registry with malicious nodes and cause the network to fail.