Connect a Mobile Device

Pair a phone by enabling desktop network access and scanning the secure QR code generated in Central Connections. For the connection architecture, see Connections.

Supported platforms

Desktop	Mobile
macOS, Windows	iOS, Android

Choose LAN or Tailscale

Route	Requirement	Ordering
Tailscale	Desktop and phone signed into the same tailnet	Preferred when discovered
LAN/Wi-Fi	Phone can reach the desktop on the local network	Fallback and legacy pairing route

The desktop puts one URL per reachability class into the QR. The phone tries the ordered candidates automatically.

Prerequisite

Before scanning, sign in to the Aiola mobile app with the same Aiola account that is signed in on the desktop. Pairing sends the phone account’s bearer token, and the desktop rejects a bootstrap created by a different account.

Pair the phone

Open Connections

In Aiola Desktop, open Central Settings → Connections.

Enable the network server

Turn on Allow LAN connections. Wait for the local server to restart and show its connection URLs.

Allow Windows Firewall

On Windows, choose Allow when Windows Firewall asks to allow Aiola on private networks. Without this permission, phones on the same Wi-Fi cannot connect.

Generate a code

Under Devices, select Add. Keep the dialog open while the secure QR code is generated.

Scan from the phone

In the Aiola mobile app, open its QR scanner and scan the desktop code. The phone exchanges the short-lived token for a device credential and tests the candidate URLs.

Pairing payload and expiration

The QR carries this version-3 shape:

{
  "v": 3,
  "name": "Desktop server name",
  "baseUrl": "http://lan-address:port",
  "baseUrls": ["ordered Tailscale or LAN URLs"],
  "pairToken": "short-lived secret"
}

Value	Lifetime or behavior
Pairing token	120 seconds; the open dialog refreshes it shortly before expiry
`baseUrl`	Legacy single-route fallback, preferring LAN
`baseUrls`	Version-3 ordered automatic failover list
WebSocket ticket	Single-use; 60 seconds

If scanning fails after the token expires, keep or reopen the dialog to generate a new code.

Device status

Field	Meaning
Device name	Paired device label
Platform	iOS, Android, Web, Desktop, or Unknown platform
Online/offline	Current connection state
Remote address	Address used by the live connection
Last seen	Most recent presence
Paired/connected time	Stored pairing or live connection timestamp

The desktop refreshes status every 10 seconds, on window focus, and when the page becomes visible.

Revoke and re-pair

Select Revoke access beside a paired device and confirm. Aiola revokes its credential, invalidates issued tickets, and closes matching connections. Scan a new QR code to restore access later.

Troubleshooting

Symptom	Check
No connection URLs	Confirm Allow LAN connections is on and the local server finished restarting
Windows phone cannot connect	Allow Aiola through Windows Firewall on private networks
Tailscale route fails	Confirm both devices are signed into the same tailnet; the phone will then try LAN if available
QR is rejected	Generate a fresh code; the pairing token lasts 120 seconds
Fresh QR is rejected while both devices are reachable	Confirm the phone and desktop are signed in to the same Aiola account, then generate a new code
Previously paired phone is rejected	The credential was revoked or replaced; pair again
Device cannot be revoked	Unmatched live connections have no paired device credential; revoke applies only to paired devices

Allow LAN connections exposes the local Aiola server on the listed network interfaces. Revoke devices you no longer recognize.

Getting Started

Workspaces & Central

Chat & AI

Project Operations

Monitoring

Connections

Settings

Setup Guides

Reference

Connect a Mobile Device

Supported platforms

Choose LAN or Tailscale

Prerequisite

Pair the phone

Pairing payload and expiration

Device status

Revoke and re-pair

Troubleshooting

​Supported platforms

​Choose LAN or Tailscale

​Prerequisite

​Pair the phone

​Pairing payload and expiration

​Device status

​Revoke and re-pair

​Troubleshooting

Supported platforms

Choose LAN or Tailscale

Prerequisite

Pair the phone

Pairing payload and expiration

Device status

Revoke and re-pair

Troubleshooting