How LocalSend Finds a Peer When the Network Is Uncooperative

LocalSend's discovery system answers a specific problem: how can a nearby device become a usable transfer peer when the network may drop multicast, block ports, or expose several addresses for the same machine? This chapter follows the path from a UDP announcement to confirmed HTTP reachability, then explains why LocalSend escalates from cheap known-address checks to a bounded subnet scan. The practical result is a way to distinguish “the device announced itself” from “the app has confirmed a peer it can safely target.”

UDP announces; HTTP confirms

The first design choice is a division of labor. LocalSend's protocol uses UDP multicast to announce that a device is present, but it uses HTTP to confirm the relationship. The announcement is not a miniature file-transfer request and it is not a complete response protocol. It is a compact description of the sender: an alias, protocol version, optional model and device type, a port, a transport choice such as HTTP or HTTPS, a fingerprint, and whether a download interface is active.

The default IPv4 multicast group is 224.0.0.167, and the default port is 53317. The port is also the default for the device's HTTP server, although the protocol allows configuration when a network or another process makes the default unavailable. The choice of a multicast group in the local range is practical rather than universal: the implementation notes that some Android devices reject other multicast ranges. A protocol that wants to work across phones and desktops has to account for those platform-specific constraints before it can discuss elegant discovery algorithms.

When another LocalSend instance receives the datagram, it does not answer with a UDP message as the main path. It parses the announcement, ignores it if the fingerprint is its own, and makes a registration request to the announcing device's HTTP server. The route is POST /api/localsend/v2/register. If registration succeeds, the response provides the peer's current information and the application can retain the HTTP channel as a confirmed way to reach that device.

That sequence makes the two transports do different jobs. UDP is well suited to a quick “who is nearby?” signal because one sender can reach many listeners without knowing their addresses. It is also lossy and difficult to use as a reliable, stateful data path. HTTP is a better place to establish a two-way relationship: it can succeed or fail explicitly, return structured information, and become the control channel for the transfer that follows. LocalSend does not ask multicast to provide guarantees it was not designed to provide.

The distinction also limits what the device list means. A name appearing in a multicast packet is evidence of a claim made on the network, not proof that the peer is reachable at the advertised port. Registration is the confirmation step. The application only has a useful channel after the unicast request has reached a server and received an acceptable response. This is why a crowded or noisy LAN should not necessarily produce a crowded list of actionable devices: visibility and reachability are filtered at different stages.

The current implementation repeats announcements in a short burst rather than trusting one datagram. That is a small but important reliability decision. A packet can be lost, a mobile process can become ready a moment after another device announces, or a network interface can take time to join the multicast group. Repetition improves the chance that peers meet without requiring a permanent discovery service. It does not make multicast reliable in the general sense; it simply makes a transient local signal less brittle.

The per-interface behavior matters as well. A computer may have Wi-Fi, Ethernet, a virtual adapter, and more than one address. The multicast layer binds sockets for usable interfaces and sends announcements through them, rather than assuming that one operating-system socket represents the whole machine. IPv6 discovery is supported as an extension, and link-local IPv6 addresses retain an interface scope. Without that scope, an address such as fe80::1 can be ambiguous or unreachable even when the peer is physically on the same link.

The implementation also leaves multicast loopback enabled and drops messages with its own fingerprint. That combination lets separate LocalSend instances on one host observe each other while preventing a process from treating its own announcement as a remote device. The fingerprint is not being used as a secret here. It is a stable identity marker for suppressing self-discovery and, in HTTPS mode, for connecting the network announcement to a certificate-based identity later in the process.

sequenceDiagram participant A as Announcing device participant M as Local multicast participant B as Discovering device participant H as HTTP server A->>M: Send announcement metadata M-->>B: Deliver datagram when available B->>B: Ignore if fingerprint is own B->>H: POST /register H-->>B: Return peer information B->>B: Store confirmed HTTP channel alt Multicast is unavailable or no confirmation arrives B->>H: Probe a known address B->>H: Probe local subnet hosts H-->>B: Confirm only responsive peers end

The diagram's fallback branch is not a second interpretation of multicast. It is a separate discovery method. A device that cannot receive multicast may still run an HTTP server, and a device that cannot hear an announcement may still be able to probe a peer at a known address. LocalSend therefore treats discovery as a set of channels that converge on the same confirmation step rather than as one protocol feature that must work everywhere.

In HTTPS mode, the announcing device's fingerprint has an additional role. The discovering side can use it as the expected certificate fingerprint when it registers, so the connection is not merely “some valid self-signed certificate.” The certificate and the discovery claim must line up. The full implications of that check belong to the security discussion, but the discovery consequence is already clear: the announcement carries information that helps the later HTTP connection decide whether it is talking to the peer the user meant to select.

Fallback discovery is a cost ladder

When multicast does not produce confirmations, LocalSend does not immediately scan every possible address. Its staged discovery process starts with the cheapest evidence it already has. It can probe known HTTP channels, including addresses associated with favorite devices, while it sends the normal announcement burst. If a known device answers, the network has demonstrated that at least one low-cost path works, so a broad scan is unnecessary.

Only when no confirmation appears during a grace period does the implementation escalate to scanning local IPv4 /24 subnets. A /24 is a familiar home-network shape, but it is not a description of every network LocalSend might encounter. Routed networks, unusual subnet masks, client isolation, blocked ports, and networks separated by firewalls can all make the scan incomplete or irrelevant. The feature is best understood as a bounded fallback for common flat LANs, not as a universal network mapper.

The scan is bounded in two ways. It does not probe the local interface's own address, and it limits concurrent register requests to 50. The core also uses a short default timeout of 500 milliseconds for discovery registration. Those limits express a trade-off: a scan should finish quickly enough to be useful, but it should not open hundreds of simultaneous connections or wait indefinitely for hosts that are not participating. A timeout is not evidence that a host is absent; it is a decision about how much delay discovery is allowed to impose.

The staged rule is also a form of feedback. A confirmation from a favorite device does more than add one row to the list: it demonstrates that the current interface, port, and transport can reach at least one peer. Continuing to scan every address after that would spend network and battery resources without improving the immediate answer. Conversely, the absence of any confirmation is useful evidence that the cheap channel may be unavailable, so the application has a reason to pay for broader probing.

Known-channel probing is not blind trust in an old address. The probe still performs the current registration exchange, and HTTPS can still require the peer certificate to match the expected fingerprint. What persists is the route hint and the user's relationship with the device, not a permanent exemption from reachability or identity checks. This is why a favorite can survive an IP change without becoming a bypass around the protocol.

The same reasoning applies to IPv6. A peer may have both an IPv4 channel discovered through a subnet scan and an IPv6 channel discovered through multicast. They can belong to one stored device while remaining different network paths, with the IPv6 scope retained when a link-local address needs an interface identifier. LocalSend's abstraction is therefore not “one device equals one address”; it is “one device can have several confirmed channels, each with its own current status.”

This cost ladder gives each discovery method a different role:

  • Multicast announcement is the cheapest way to ask many local peers to identify themselves, but it depends on multicast support and permissions.
  • Known-channel probing is targeted and efficient, especially for devices the user has already trusted or favorited, but it cannot find a genuinely unknown address.
  • Subnet probing trades network work for coverage on ordinary IPv4 LANs, but it is slower, noisier, and bounded by the topology and firewall rules.
  • Manual addressing is the explicit fallback when the user knows the peer's IP and discovery does not. It removes the need for discovery, but not the need for the HTTP server and the relevant transport/security checks.

The device store makes those channels feel like one product feature. A discovered device is keyed by its fingerprint, not by one IP address. Each successful confirmation can add or refresh an HTTP channel, and the store retains channel status and a bounded history of confirmations. If the same laptop answers first on Wi-Fi and later on Ethernet, the application can preserve one logical device with more than one route. If a route fails, the application can mark that channel as unavailable and prefer another confirmed route when one exists.

This merge rule solves a user-facing problem that raw network discovery cannot. IP addresses are properties of paths and interfaces; users usually think in terms of devices. Without fingerprint-based merging, a multi-homed computer could appear as several peers, and a changed address could look like a new device. With merging, the device identity persists while the available routes change. That persistence is also what makes favorites useful: a favorite can be probed directly even when multicast is absent, and a successful response can refresh the current address without discarding the user's relationship with the device.

There is a security qualification to this convenience. In HTTPS mode, the fingerprint is tied to the certificate and can be used for pinning. In HTTP mode, the protocol uses a random generated fingerprint. The latter can still support deduplication and remembered channels, but it does not turn an unencrypted connection into an authenticated one. The same word—fingerprint—therefore supports two different levels of assurance depending on the transport. Treating the device store as an identity database without preserving that distinction would make the UI simpler but the explanation false.

The operational failures are equally concrete. A router may enable access-point isolation, a Windows network may be classified as public, macOS or iOS may withhold local-network permission, or a VPN may block LAN traffic. In those cases the discovery algorithm may be correct and still receive no response. A mobile operating system can also reclaim multicast sockets when an app is suspended; the implementation reports that failure so the app can restart discovery. If the HTTP server is not reachable, no amount of successful UDP parsing can make a transfer begin.

That is why “device not visible” is not one diagnosis. It can mean that the announcement was never delivered, that the response could not reach the announcing device, that the HTTP port was blocked, that the server was not running, or that the peer failed a transport or identity check. LocalSend's staged design narrows those possibilities by changing the path: probe a known address, scan a likely subnet, or let the user enter an address directly. Each result supplies different evidence about where the failure sits.

By the end of discovery, LocalSend has not sent a file. It has established a reachable channel and attached that channel to a logical peer. That restraint is the point. The first network response makes a transfer possible, not permitted. The next stage begins with metadata and a receiver decision, asking what the peer wants to accept before any file content is allowed onto the wire.

References