Connect Mobile

Use Connect Mobile to pair the native phone app with your desktop.

Pair on the same network

1. Install Orchestrator Mobile from the App Store or Google Play. Open the desktop app and go to Settings → Connect Mobile.
2. Put both devices on the same trusted network. In Connect Mobile, choose Generate to turn on the separate mobile connection. The app shows an address, password, and QR when a reachable endpoint is ready; a blurred or preparing QR cannot pair a phone.
3. In the mobile app, tap Pair Desktop during onboarding. Newer mobile builds call this button Pair a machine. From an unpaired screen, tap Scan pairing code. The app opens the scanner. Scan the desktop QR. Treat the entire QR/link as a password.
4. If scanning fails or camera access is unavailable, tap Enter details manually on the pairing screen and enter the address, port, and password shown on the desktop. The listener normally starts at port 3011 but can choose another free port. Use the displayed address, not 127.0.0.1, which means the phone itself when entered there. A failed scan offers Try again.
5. Open the paired computer in the mobile app, choose a project and worker, then open its Chat or Terminal UI. An approval request needs your response in the session. Pull request and review screens show repository and reviewer state. If a control is absent, check the session interface and harness capability rather than assuming the phone created a second session.

Turning mobile access off closes the authenticated listener. Regenerating its password invalidates old pairing credentials. If the phone reports an incompatible pairing or identity contract, update both apps; current desktop pairing does not generate a legacy v1 fallback.

Signed out, Connect Mobile reaches the computer away from home through a quick tunnel whose address changes when the computer restarts, so a paired phone then needs a new code. Signed in, Connect Mobile links the computer to your account and gives it a fixed https://h-….useao.dev address instead. Signing in while Connect Mobile is already on links it too, with nothing else to turn on; scan the refreshed code once. A computer an AO account already holds is left alone: signing in to another account does not move it there, and one removed from its account on another device is not listed again. Allow access from your devices in Settings → Remote hosts links it to the account you are signed in to. The address stays the same after restarts and sleep, so a paired phone keeps working without a new code. When AO Cloud cannot give the computer a fixed address, it uses a quick tunnel, as when signed out, until it can. Linking the computer to another AO account gives it a new address in that account. After the computer has been asleep or offline for more than 5 minutes, it takes about a minute to be reachable again. Orchestrator runs the remote-access connector with cloudflared. If it is missing, Orchestrator downloads a pinned copy into ~/.ao/data/bin and checks its SHA-256: by itself on a computer linked to your account, otherwise when you click Install cloudflared. Connect Mobile offers Install with your package manager only when that download fails. A LAN code can be ready first; scan the refreshed QR after the remote endpoint appears. Test once with the phone off the home Wi-Fi. A successful home-network connection alone does not prove away-from-home access.

Use this desktop from another machine

When both computers are signed in to the same AO account, you do not need the address or password. On the computer you want to connect to, open Settings → Remote hosts and turn on Allow access from your devices. Orchestrator links the computer to your account under its computer name, then starts its authenticated remote listener and a cloudflared tunnel at the computer's fixed address; this takes about 20 seconds. Your other desktops signed in to the account with Connect to remote hosts on, and phones signed in to it, list the computer within about 30 seconds. Turning the switch off stops remote access, which also disconnects phones paired through Connect Mobile, and removes the computer from your account. Cloudflare terminates TLS and can read tunneled traffic.

Connect a VM or other headless machine

On a fresh Ubuntu 24.04 x64 VM, sign in over SSH as a non-root user with sudo and run:

curl -fsSL https://raw.githubusercontent.com/OrchestratorInc/agent-orchestrator/main/scripts/bootstrap-self-hosted.sh | bash

This installs the latest stable AO; for the newest nightly, end the command with bash -s -- --nightly.

It installs AO as a service that keeps running after you log out, then prints a sign-in link and a QR code. Open the link on any device, or scan the code with your phone, check that the page shows the same code as the terminal, and sign in to your AO account. The VM joins your account the same way as a desktop, at a fixed address, and keeps none of your sign-in. Your desktops and phones signed in to that account list it within about 30 seconds; the desktop looks for new machines only while its window is open.

If AO is already installed on the machine, or the link expired, run ao remote-host link there for a new link. See Self-hosted remote hosts for other install options, agent setup over SSH, and troubleshooting.

Pair without an account

To connect a machine without linking it to your account, open Orchestrator on the machine you want to connect to. With the current ao CLI, show its existing connection address and password without changing remote access:

ao remote-host status --show-password

If status reports Remote host disabled, run:

ao remote-host enable --tunnel-only
ao remote-host status --show-password

The tunnel starts asynchronously; run status again until an HTTPS address appears. On the other desktop, sign in to Orchestrator and open Settings → Remote hosts → Add host, then enter that address and connection password. Treat these details as credentials. Cloudflare terminates TLS and can read tunneled traffic. Until a signed-in desktop adds the machine, it uses a quick tunnel whose address changes on restart; once added, it moves to a fixed address that your devices follow.

If the host already has LAN access enabled, its displayed HTTP address works only on a trusted reachable network. Use ao remote-host enable --tunnel to add HTTPS access while retaining that LAN listener; switching to tunnel-only mode requires disabling it first and invalidates the old password.

If ao is missing from your Mac's PATH or points to an old install, use the current desktop app's bundled CLI instead: "/Applications/Agent Orchestrator.app/Contents/Resources/daemon/ao" remote-host status --show-password. Adjust the app path if you installed or named it differently; the same binary supports remote-host enable --tunnel-only.

On macOS, Quit / Cmd+Q closes the desktop window and removes AO from the Dock while its tray, daemon, and enabled remote access keep running. Use the tray's Quit AO Completely to stop the app-owned server. The host must stay awake and reachable; closing the window does not enable remote access by itself.

Tailscale

iPhones cannot connect through the current raw Tailscale endpoint. Use a managed HTTPS endpoint instead. iOS blocks cleartext requests to 100.64.0.0/10, and the current v2 offer does not advertise Tailscale HTTPS endpoints. The current desktop panel has no connection-method selector or separate visible TLS control, and automatic TLS setup is incomplete. Android behavior for a raw Tailscale endpoint is unverified.

If Connect Mobile shows a secure-pairing failure reason, follow that text. A direct plaintext LAN endpoint remains suitable only for a trusted network. The phone races only the endpoints in the offer, and uses TLS only when an endpoint is marked secure: true.

Do not point tailscale serve, a public proxy, or port forwarding at the unauthenticated primary daemon. Orchestrator's secure endpoint setup targets the separate authenticated mobile listener.

Security model

• The primary API stays on 127.0.0.1, with no network-facing bind or added authentication. Its host cannot be changed; do not expose it with HOST=0.0.0.0, a public reverse proxy, or port forwarding.
• Connect Mobile's separate listener is disabled by default, binds to the LAN only while enabled, requires a bearer connection password, and exposes app API routes without daemon-control routes. Direct HTTP transport is for trusted networks; a managed connector endpoint marked secure: true can wrap this authenticated path for remote access. Current Tailscale entries are advertised as plaintext.
• Exactly GET /api/v1/identity is unauthenticated. It returns an opaque host identity and mobile contract version, which QR pairing checks before presenting a credential. The current link includes the host identity and available endpoints, and carries the credential in its fragment. It does not expose sessions. New manual connections can continue after ordinary identity-check errors, so enter only a host you trust.
• Other mobile REST and terminal connections require the rotating bearer password. Repeated failed authentication is locked out per source.
• Shutdown, telemetry, mobile-control, and browser-control routes remain loopback-only.
• Mobile settings live at AO_DATA_DIR/mobile/config.json (normally ~/.ao/data/mobile/config.json). The file stores the rotating password so the desktop can redisplay it and is written with mode 0600; authentication comparisons use an in-memory hash. It is not a persisted password-hash-only store.

Do not share pairing screenshots or links. Turn push notifications on or off on the phone itself; use Remove in Connect Mobile to clear a paired-device record. Removing a device record is not a substitute for rotating the shared connection password: regenerate that password if a phone or QR/link was lost or exposed, then pair trusted phones again. Made while the desktop is signed in to AO, a new password also gives the computer a new tunnel at the same address; the address can take about a minute to answer again. Once the account lists the computer with its own key, which a link from this version adds when both the computer and AO Cloud support it, a device that holds only the computer's old credentials cannot serve its address or move it, because AO Cloud also needs a signature from that key. A computer linked by an older version has no key yet: make the new password while signed in, or sign in and remove the computer from the account too. A lost device that is still signed in to your AO account can still change that account's computers. Keep direct plaintext traffic off untrusted networks. The historical LAN-only design describes the listener itself; current managed secure endpoints do not change the primary listener boundary.

What mobile supports

The Expo/React Native app is a native control surface over the same daemon resources as desktop. New mobile sessions prefer Chat when a compatible installed harness is available; Terminal UI remains an explicit compatibility choice.

Mobile supports structured Chat, Terminal UI, session creation, the same capability-gated Chat/TUI handoff, approvals and structured input, model and agent controls, compaction and rollback when the session advertises those capabilities, voice dictation, attachments, a workspace shell, and generated previews.

Mobile also exposes pull request, workspace review, and reviewer-run views. Push notifications need mobile permission, a paired device, and a running daemon with network access to its push service. Pairing alone does not guarantee push delivery. Supported macOS hosts can enable keep-awake in Connect Mobile; the host must remain awake and reachable for interactive access.

If the phone cannot connect

Keeping a MacBook reachable with its lid closed

The sidebar Stay Awake button prevents idle sleep. On eligible Apple Silicon MacBooks (macOS 13–27) with the bundled desktop helper, Keep this Mac awake in Mobile settings also includes closed-lid wakefulness. It starts immediately and works independently of Connect Mobile. No phone connection or enabled mobile listener is required. Turning off mobile access leaves the awake request active. Turn off Keep this Mac awake or the sidebar awake button to release both modes. The saved awake preference is restored after a daemon restart even when mobile access is off.

Explicit opt-in registers a local recovery helper without an administrator password. Short daemon leases and launchd restart recovery handle abandoned requests. The UI distinguishes saved intent, an armed native control, and safety/recovery stops. macOS authentication stays in effect; an external display is not required by the implementation.

Keep the Mac on a ventilated surface, not in a closed bag. Lid wakefulness stops below 10% battery, on unknown battery state or at critical thermal pressure. After charging/cooling, turn Keep this Mac awake off and on to restart. Do not run another lid utility concurrently; macOS's lid control is global.

A reviewer verified basic lid-close operation and continued phone connectivity on one macOS 26 MacBook. Full physical compatibility validation, including crash recovery and macOS 27, is pending. A successful probe or "armed" status is not a connectivity guarantee on every OS/hardware combination. Test a short lid-closed session on your machine before relying on it unattended. ADR 0005 records current evidence and the release gate.

Helper versions, plist, leases and recovery journal live under ~/.ao/data/wake, shared by AO instances of the same login using the default ~/.ao/data durable data root. Custom or scratch AO_DATA_DIR roots disable native lid control so isolated runs cannot affect production state or host power. Ordinary Keep awake remains available. Turning the feature off retains recovery registration but ends requests. To remove registration, open the lid, turn the option off in every AO instance and wait for recovery to finish, then run launchctl bootout gui/$(id -u)/com.aoagents.mobile-wake. Do not delete an unfinished recovery journal. Re-enabling the option registers the helper again.

An existing compatible helper is reused across app builds, rather than replaced while sessions may be active. To upgrade that helper, use the removal steps above with the lid open, then enable the option again; fresh registration removes stale helper copies.

Native protocol version 2 stores coordinator state inside the default durable data root. An existing version-1 registration is never replaced automatically; open the lid, stop all old wake sessions and unload its registration before opting in again. Retain any unfinished legacy recovery journal under ~/.ao/wake until recovery has completed.