# How it works

> The coordination service, direct connections between devices, and the relay that steps in when a direct path isn't possible.

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](https://www.wireguard.com/), 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

> [!NOTE]
> Devices that are already connected directly keep talking to each other even if the coordination service is briefly unreachable. New devices and changes wait until it's back.

## Joining a network

1. You install the app and sign in, or start it with an [auth key](/manage/auth-keys).
2. The device creates its keys and registers its public keys with the coordination service.
3. If [device approval](/manage/machines#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`](/reference/cli#status) and look at the `PATH` column: `direct` or `relay`.

## Addresses and names

| What | Range or format |
|---|---|
| Devices | `100.64.0.0/10`, one address per device, unique across all workspaces |
| [Services](/features/services) | `100.100.0.0/16` |
| Device names | `<name>.<your-domain>`, and the short `<name>` on its own (see [Easy names](/features/easy-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](/concepts/security) for the details.