Sign in on your iPhone

New Handsfree Mac and Linux hosts use the same account as your iPhone. This internal release uses Clerk Development. It is separate from your Apple ID, Tailscale login, and coding-provider subscription.

Create an account or sign in#

Install the latest internal TestFlight build. On first launch, choose Create account / Sign in. The iPhone opens Clerk’s secure hosted account page in the system authentication browser. Create an account there or choose the existing-account sign-in option. Complete the requested email verification or supported provider login, then approve Handsfree access. You return to the app automatically.

Use the same account shown in Mac or Linux setup. The app stores its OAuth credentials in iOS Keychain; they are never exposed to the web interface. If you cancel, the welcome screen stays available with a retry button. A network failure does not require reinstalling the app.

Pair a Mac or Linux host#

1. Finish account, Tailscale, agent, and project setup on the host.
2. Turn on Tailscale on your iPhone and connect to the same tailnet.
3. In Handsfree, choose Add computer and scan the host’s new QR code.
4. The host verifies your account, then issues this iPhone a revocable device credential.
5. Choose a project and start a small conversation to verify the complete connection.

New account-enabled pairing requires the host’s HTTPS address. Don’t substitute a plain HTTP LAN address. Pairing codes expire after ten minutes and are single-use; generate another if one was already scanned. A code does not override the same-account requirement.

Updating from an older iPhone build#

Older saved connections are retained separately. Choose Use existing connections without an account on the welcome screen to open them. This is explicitly legacy access, not account-protected access. New account-enabled hosts require sign-in even if you choose legacy mode.

After signing in, pair an updated host again so its connection is saved under your account. Other accounts on the same iPhone do not see your saved host credentials. Upgrading the Mac app can require fresh pairing because old device credentials were not account-bound.

Sign-out and account switching#

The account bar shows the active account and a Sign out control. Sign-out stops listening, disconnects this iPhone, clears local account credentials, and attempts remote OAuth revocation. It does not delete your Clerk account, erase project history, or stop work already submitted to an agent. Saved host credentials stay in their separate account namespace so you can return later.

For a lost phone, revoke it in each host’s setup page. Logging out of Clerk in another browser is not a central emergency-revocation system for existing host device tokens. Internal account deletion is currently handled by the beta administrator; ask Todd rather than assuming sign-out deletes your account.

Troubleshooting#

Sign-in was canceled: choose Create account / Sign in again. Nothing was paired.

Verification email missing: check the email address and spam folder, and use Clerk’s resend option. This is a development instance; ask Todd if an internal account or sign-in method needs attention.

Sign-in expired: reconnect to the internet and sign in again. Use Clear saved sign-in and retry if the stored account cannot be recovered. Your host history stays on the host.

Use the same account: compare the account shown on the phone with host setup. Separate accounts created under different emails are not automatically merged.

HTTPS required / invalid certificate: use the private HTTPS URL produced by host setup and verify Tailscale. Do not bypass certificate validation.

No projects: complete host setup and save project selections. Signing into Handsfree does not automatically discover projects on your phone.

No TestFlight access: ask Todd to add you to the internal tester group. Internal testing requires appropriate App Store Connect access; there is not a public installation QR code yet.

See Mac setup, headless Linux setup, and connection troubleshooting.