Network and ports
easysync connects devices in three ways. Which of them works depends on the network between the devices. This page lists what each way needs, so that you can configure a firewall or a router.
The three ways #
- Directly on the same network. A device announces itself on the local network and finds the others there. Then it connects to the other device with QUIC.
- Directly across networks. If one device is reachable from the other at an address that it knows (for example because you opened a port), the connection works the same way. easysync does not punch holes through routers.
- Through a relay. Both devices connect out to a relay, which forwards the encrypted data. The relay sees the IP addresses, timing and volume of these connections (What the relay sees). This works from behind almost every network, and it is the only way for a browser.
A session that starts on a relay stays on the relay until it ends. The next connection tries the direct ways first.
The end-to-end encryption between two devices is a Noise session that runs inside the connection. It does not depend on the way: the same session protects the content on a direct QUIC connection and on a connection through a relay, which carries it over WebSocket over TLS.
Ports and protocols #
| What | Protocol and port | Needed for |
|---|---|---|
| Direct connection between devices | QUIC over UDP. The preferred port is 47017; if it is taken, a free port is used. The port in use is announced to the local network. You can set the address with --listen or listen in config.toml. | Ways 1 and 2: the receiving device must accept incoming UDP on this port. |
| Discovery on the local network | mDNS: multicast on the standard mDNS addresses and UDP port 5353, service type _easysync._udp | Way 1. It is best effort and does not cross routers, guest networks with client isolation or VPN boundaries. |
| Relay | TLS over TCP. A relay listens on 0.0.0.0:8443 by default, which operators usually map to port 443. The protocol is WebSocket over TLS. | Way 3, and for a relay operator: incoming TCP on that port. |
| Relay health check | Plain HTTP on 127.0.0.1:8081, on the loopback interface only | The relay checks itself; do not expose it. |
A device that only uses relays needs no incoming connections at all, only outgoing TLS to the relay.
What the announcement on the local network shows #
The announcement is visible to everybody on the network, including a café or hotel Wi-Fi. It contains only the version of the protocol, a value that changes every hour and that only your paired devices can recognise, and the QUIC port, together with the IP addresses of the device and a random instance name that changes at every start and on every network change. It contains no device name and no stable identifier. The value is the same everywhere within the same hour, so someone who watches several networks in the same hour can recognise it. Threat model in plain words lists this among the limits.
Firewalls and prompts #
- Windows asks once for permission for incoming connections the first time easysync listens. Allow it on private networks to find your devices directly. Without it, the app still works through a relay. The installer adds no firewall rule.
- macOS has a permission for the local network, which the app declares. The prompt has not yet been tried on a Mac. If devices on the same network are not found directly, check that permission.
- Linux with a firewall: allow incoming UDP on the QUIC port for the local network, and multicast on UDP port 5353.
- Containers. mDNS discovery works only with host networking (
--network host). Without it only relays and known addresses work, and the QUIC port must be published for UDP.
Which way did my devices use? #
The column CONNECTION of easysync peer list says direct or relay for each connected device. A relay session is cut off after the session lifetime of the relay, one hour by default, and continues by itself; a transfer in progress resumes.