Connect Mobile

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

Pair on the same network

1. Install the Tallpine mobile app. 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.

Tallpine manages a remote-access connector using cloudflared, which the macOS app includes. On Windows and Linux, if Connect Mobile says remote access is unavailable, use its Install cloudflared control and wait for the connector status to become ready. 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. The managed connector's address can change when it restarts, so use a refreshed offer if the old endpoint stops working.

Use this desktop from another machine

When both computers are signed in to the same Tallpine account, you do not need the address or password. On the computer you want to connect to, open Settings → Remote hosts (shown with Developer mode on) and turn on Allow access from your devices. Tallpine starts its authenticated remote listener and a cloudflared tunnel, then links the computer to your account under its computer name; this takes about 20 seconds. On Windows and Linux, if cloudflared is missing, the switch offers Install cloudflared. 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.

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

tallpine remote-host status

If status reports Remote host disabled, install cloudflared using Connect Mobile → Install cloudflared, then run:

tallpine remote-host enable --tunnel-only
tallpine remote-host status

The tunnel starts asynchronously; run status again until an HTTPS address appears. On the other desktop, sign in to Tallpine 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; quick-tunnel addresses can change on restart.

If the host already has LAN access enabled, its displayed HTTP address works only on a trusted reachable network. Use tallpine 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 tallpine is missing from your Mac's PATH or points to an old install, use the current desktop app's bundled CLI instead: "/Applications/Tallpine.app/Contents/Resources/daemon/ao" remote-host status. 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 Tallpine from the Dock while its tray, daemon, and enabled remote access keep running. Use the tray's Quit Tallpine 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. Tallpine'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, mobile-control, and browser-control routes remain loopback-only.
• Mobile settings live at TALLPINE_DATA_DIR/mobile/config.json (normally ~/.tallpine/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. 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

Ordinary Keep this Mac awake prevents idle sleep; normal lid sleep remains allowed. Eligible Apple Silicon MacBooks (macOS 13–27) with the bundled desktop helper can opt into Keep awake with lid closed. Enabling this mode also enables Keep this Mac awake in the same request. It starts while Connect Mobile is on and the listener is serving. Your phone does not need to maintain an active socket. Turning off mobile access, Keep awake or the lid option releases the request. Turning off Keep awake in desktop settings also turns off the lid option; turning off just the lid option keeps idle wake on.

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 the lid option 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 ~/.tallpine/data/wake, shared by Tallpine instances of the same login using the default ~/.tallpine/data durable data root. Custom or scratch TALLPINE_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 Tallpine instance and wait for recovery to finish, then run launchctl bootout gui/$(id -u)/ee.justdev.tallpine.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 ~/.tallpine/wake until recovery has completed.