How it works

Underpass has three parts. A small app runs on each of your devices. A coordination service tells those devices about each other. A relay carries traffic only when two devices can't reach each other directly. Your data travels between your devices, encrypted with WireGuard, and never through the coordination service.

The coordination service

The coordination service runs at coord.getunderpass.com. Each device keeps a connection open to it and is told whenever something in your network changes: a device joins or leaves, an address changes, an access rule is saved.

It stores:

• each device's public WireGuard key and discovery key, its name, address, operating system and app version
• your workspace's settings: access rules, DNS settings, services, apps, routes and tags
• tokens and keys as SHA-256 hashes only, never in plain text

It never sees:

• your devices' private keys, which never leave the device
• the private keys of HTTPS certificates, which are made on the machine
• any of your traffic

Joining a network

1. You install the app and sign in, or start it with an auth key.
2. The device creates its keys and registers its public keys with the coordination service.
3. If device approval is on, an admin approves it.
4. The device gets a private address from 100.64.0.0/10 and a name, like laptop.
5. From then on it receives the list of the other devices it may reach, and keeps it up to date.

A device counts as online if it has checked in within the last 90 seconds.

Direct connections

Devices connect straight to each other whenever possible. To get through home routers, hotel Wi-Fi and most firewalls, each device:

1. Learns its public address. It asks a STUN server which address and port it appears as, every 20 seconds and whenever its network changes.
2. Knocks at the same moment as the other side. Routers only let in replies to traffic they've seen go out, so both devices send to each other at nearly the same time. Each router sees the other side's packet as a reply and lets it through. This is called hole punching.
3. Keeps checking the path. A direct path is checked every 3 seconds. If it stops answering for 8 seconds, traffic moves to the relay.

Switching between direct and relay never restarts the connection: calls, SSH sessions and file copies keep going.

The relay

Some networks block every direct path. Then traffic goes through the relay. It:

• forwards only WireGuard ciphertext: it can't read your data
• connects only devices in the same workspace, using a signed pass from the coordination service that's valid for 10 minutes and renewed automatically
• limits each device to 2 MiB/s (4 MiB bursts), so one device can't slow down others

While a connection is relayed, the devices keep trying for a direct path every 35 to 60 seconds, and move to it as soon as it works.

To see how each of your devices is connected right now, run underpass status and look at the PATH column: direct or relay.

Addresses and names

Encryption

All traffic between devices is encrypted end to end with WireGuard. Each device has its own key pair, and its private key is stored only on that device. See Security for the details.