> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiola.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Connections: Pair Devices over LAN or Tailscale

> Learn how paired devices reach the desktop over LAN or Tailscale, exchange short-lived pairing codes, and receive device access you can revoke.

Connections makes the desktop's local Aiola server reachable from a paired phone or another Mac without exposing a reusable account token in the connection code. For setup steps, use [Connect Mobile](https://docs.aiola.app/guides/connect-mobile.md).

## Architecture

| Component | Responsibility |
| - | - |
| Desktop main process | Starts/restarts the local server, chooses the listening port, enumerates network endpoints, and orders them by preference |
| Desktop renderer | Requests a short-lived bootstrap, builds the version-3 QR payload, and shows device presence/revocation controls |
| Local Aiola server | Exchanges the bootstrap for a device credential, issues WebSocket tickets, records device metadata, and closes revoked connections |
| Mobile client | Scans the QR, exchanges the bootstrap, stores the device credential, and tries endpoint candidates in order |

## Desktop local server

The desktop server binds to loopback until **Central Settings → Connections → Allow LAN connections** is enabled. It tries the mode's preferred port and may select another available port, so clients must use the displayed/generated endpoint rather than hard-code a port.

| Desktop mode | Preferred port |
| - | - |
| Production | `47821` |
| Isolated instance | `47831` |
| Preview | `47921` |

## LAN binding

Enabling **Allow LAN connections** restarts the local server with host `0.0.0.0`; disabling it uses `127.0.0.1`. Private IPv4 interfaces appear as Wi-Fi, Ethernet, or Local network endpoints with URLs shaped as follows:

```text theme={null}
http://<ipv4-address>:<selected-port>
```

LAN endpoints work on the same network and are marked **Not encrypted** in the app. The API is available only in the desktop app; an externally managed server must instead set `AIOLA_SERVER_HOST` and `AIOLA_ALLOW_LAN` in its service configuration and restart that service.

## Tailscale

When a Tailscale IPv4 address exists, it is preferred over LAN and labeled **Works from anywhere. Encrypted.** A MagicDNS endpoint can follow it when a tailnet address and DNS name are available.

| Priority | Endpoint kind | Reachability |
| - | - | - |
| `0` | Tailscale IP | Tailnet; encrypted |
| `1` | Tailscale hostname | Tailnet with MagicDNS; encrypted |
| `2` | Private LAN | Same local network; unencrypted |
| `3` | Other network address | Network-dependent; unencrypted |

The QR includes one address per reachability class, so the Tailscale hostname is omitted when the Tailscale IP already represents the same path.

## Pairing bootstrap

Opening **Central Settings → Connections → Devices → Add** requests a bootstrap and renders a QR code. The implementation does not ask the user to type an address.

```json theme={null}
{
  "v": 3,
  "name": "<desktop-name>",
  "baseUrl": "<legacy-lan-or-first-url>",
  "baseUrls": ["<best-url>", "<fallback-url>"],
  "pairToken": "<bootstrap-secret>"
}
```

| Property | Meaning |
| - | - |
| `v` | Pairing payload version `3` |
| `name` | Desktop display name; omitted only when unavailable |
| `baseUrl` | Legacy version-2 fallback, preferring an unencrypted LAN address |
| `baseUrls` | Version-3 failover list, best endpoint first |
| `pairToken` | One-time bootstrap secret |

The bootstrap expires after `120` seconds. While the dialog remains open, the desktop refreshes it 10 seconds before expiry, with a minimum refresh delay of 5 seconds. **Generate a new code** replaces it on demand.

## Device credentials

| Operation | Method and path | Authentication or body | Result |
| - | - | - | - |
| Create bootstrap | `POST /api/pairing/bootstrap` | Owner bearer session | `{secret, expiresAt}` |
| Exchange bootstrap | `POST /api/pairing/exchange` | Owner bearer session; JSON `{secret, deviceId?}` | Persistent device credential and metadata |
| List devices | `GET /api/pairing/devices` | Owner bearer session | Non-secret device metadata |
| Revoke device | `DELETE /api/pairing/devices/:deviceId` | Owner bearer session | `{ok: true}` |
| Create WebSocket ticket | `POST /api/pairing/ws-ticket` | Owner bearer session plus `x-aiola-device-credential` | `{ticket, expiresAt}` |

`deviceId` is optional during exchange and is capped at 200 characters when supplied. Re-pairing the same device ID replaces its previous credential. Raw bootstrap secrets, device credentials, and WebSocket tickets are returned only to callers; the server persists SHA-256 hashes and compares presented secrets with timing-safe equality. The credential store is written with file mode `0600`.

Responses that contain credentials set `Cache-Control: no-store` and `Pragma: no-cache`.

## WebSocket tickets

A paired client presents its device credential in `x-aiola-device-credential` to mint a ticket. The ticket expires after `60` seconds and is single-use. The WebSocket upgrade supplies it as the `ticket` query parameter; consuming it binds the live connection to the paired device ID.

## Failover

Version-3 clients walk `baseUrls` in the desktop-supplied order. They therefore try Tailscale before LAN when both exist, without asking the user to choose an address. The legacy `baseUrl` deliberately prefers LAN so a version-2 phone without Tailscale can pair on the same Wi-Fi.

## Presence and status

The Devices list refreshes every `10` seconds and also refreshes when the window gains focus or becomes visible. Each paired row can show:

| Field | Source |
| - | - |
| Device name | Live client, then persisted paired-device metadata |
| Platform | `iOS`, `Android`, `Web`, `Desktop`, or `Unknown platform` |
| Remote address | Live connection, then last persisted address |
| Connection state | `Offline` when no live client is attached |
| Last seen | Live or persisted timestamp |
| Paired | Credential creation timestamp |

Presence updates are persisted at most once per `60` seconds during normal activity.

## Revocation

Choose **Revoke access** on a paired device and confirm **Revoke access**. Revocation invalidates its credential and already minted tickets, then immediately closes live connections for that device. The device can connect again only by pairing with a new QR code.

## Platform notes

The desktop UI implements both macOS and Windows. On Windows, allow Aiola on private networks when Windows Firewall prompts; otherwise phones on the same Wi-Fi cannot connect. The paired client platform metadata supports iOS, Android, Web, Desktop, and Unknown.

## Security considerations

| Property | Implementation |
| - | - |
| Short bootstrap exposure | One-time secret with a 120-second lifetime |
| Scoped long-lived access | Per-device credential tied to the signed-in desktop owner |
| WebSocket isolation | 60-second, single-use ticket instead of placing the device credential in the WebSocket URL |
| Secret storage | SHA-256 hashes only; timing-safe comparisons; credential file mode `0600` |
| Owner isolation | Pairing routes require the desktop owner's bearer session |
| Revocation | Invalidates credentials/tickets and disconnects the live device |
| LAN confidentiality | None at the HTTP transport layer; use Tailscale for the encrypted route |
| Credential caching | Credential responses use `no-store` and `no-cache` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.