Connections

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.

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:

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.

{
  "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`

Getting Started

Workspaces & Central

Chat & AI

Project Operations

Monitoring

Settings

Setup Guides

Reference

Connections

Architecture

Desktop local server

LAN binding

Tailscale

Pairing bootstrap

Device credentials

WebSocket tickets

Failover

Presence and status

Revocation

Platform notes

Security considerations

​Architecture

​Desktop local server

​LAN binding

​Tailscale

​Pairing bootstrap

​Device credentials

​WebSocket tickets

​Failover

​Presence and status

​Revocation

​Platform notes

​Security considerations

Architecture

Desktop local server

LAN binding

Tailscale

Pairing bootstrap

Device credentials

WebSocket tickets

Failover

Presence and status

Revocation

Platform notes

Security considerations