Set up the Mac app preview

This guide is for the Handsfree Mac app preview. It replaces the clone-a-repository setup for people receiving a packaged Mac build. The first preview supports Apple silicon Macs and Claude Code. Codex installation and sign-in are detected, but Codex phone execution is not enabled yet.

Get the current signed, notarized Mac installer from Handsfree downloads. You do not need repository access or a source clone. The iPhone app still requires a TestFlight invitation from your beta administrator; there is no public iPhone invitation link.

Before you start#

You need your Mac, your iPhone, access to Claude Code, and Tailscale on both devices. Your Handsfree account, Tailscale account, and coding-agent account are separate. Handsfree never asks you to copy a provider API key into the app.

For the smoothest first connection, keep your Mac plugged in with its lid open. You can leave the Handsfree window closed after setup; its menu-bar item keeps the host available.

Open Handsfree on your Mac#

Download the Mac installer, open its disk image, drag Handsfree into Applications, and open Handsfree from Applications. The app includes its own runtime; you do not need Node, npm, a terminal server, or a source checkout.

If macOS blocks the build as unverified, ask the sender for a signed, notarized build. Do not disable macOS security protections. Artifacts labeled unsigned or developer-only are not coworker installers.

1. Your account#

Use this same account when signing in on your iPhone. Mac 0.2 and newer require the updated account-enabled iPhone build and a fresh pairing; older build 14 did not include phone account sign-in.

Choose Sign in or create account. Your browser opens a Handsfree sign-in page powered by Clerk. Continue with Google or use your email address and verification code. Allow the Mac app to read your Handsfree profile and email, then return to the app.

The account card should show Signed in. We intentionally use Clerk’s development environment for this internal pilot. A development label and an accounts.dev sign-in address are expected; you do not need to configure Clerk or buy a domain. Use your real email or Google account, not a shared test account. Your provider logins stay separate and local.

If you close the browser accidentally, choose Cancel in Handsfree and start sign-in again. Signing out of Handsfree stops the host but does not sign you out of your coding agents.

2. Private connection#

Install Tailscale for Mac, open it, and sign in. Allow the VPN connection if macOS asks. Use the same Tailscale account on your iPhone, or your company’s designated tailnet.

Back in Handsfree, choose Check again, then Set up private connection. If Tailscale opens an approval page, approve private HTTPS and return to Handsfree to retry. Leave public sharing, called Funnel, off.

Handsfree adds a private address while preserving existing Tailscale services. It checks that address after you start the host. If your company requires device or HTTPS approval, ask its Tailscale administrator; Handsfree cannot bypass that approval.

3. Coding agents#

Handsfree checks whether Claude Code and Codex are installed and signed in. If Claude is missing, use its Install button and follow the provider’s instructions, then choose Check agent installations again. If it is signed out, use Sign in.

Choose Test connection to send a tiny, no-tools test. This uses a small amount of your Claude allowance without accessing your projects. Then select Use in Handsfree and review the agent-access checkbox.

Enabled agents can edit files and run commands as you. Selecting projects is not a security sandbox: it selects where work starts. Only pair phones you trust.

4. Your projects#

Choose Find my projects to search common development folders. Check the projects you want on your phone. Nothing is uploaded or selected automatically. You can select several projects, search another folder, or use Browse to add a folder without Git.

Choose Save projects, or Continue to save your selection and move on. If a folder cannot be read, use Browse to select it directly. If macOS requests folder access, allow it only for the folders you intend to use.

5. Your iPhone#

Install Apple’s TestFlight app, then open the Handsfree invitation supplied by your beta administrator. A Handsfree account alone does not grant TestFlight access. There is no public invitation link in this preview.

Install Tailscale for iPhone and connect it to the same private network as your Mac.

In the Mac wizard, choose Start host, then Show connection code. In Handsfree on your iPhone, choose Scan the QR shown on my computer and scan the displayed QR code. The code works once and expires after ten minutes. Get a fresh code if necessary.

Once the Mac shows Your iPhone is connected, start a conversation on the phone and type: “Reply with connection confirmed. Do not use tools.” Wait for the reply. Then try Start talking, allow microphone and speech access, and confirm you hear the response. The Mac separately checks that the phone connected and received a successful agent response.

After setup#

Keep Handsfree running in the menu bar and keep Tailscale connected. Closing the window is fine; quitting Handsfree stops the host. The keep-awake option does not wake a closed or powered-off Mac.

You can return to setup to change projects, stop the host, generate a new pairing code, or disconnect a paired device. Disconnecting a device prevents future access but does not cancel work it already submitted.

For help, use Copy safe diagnostics. It includes app and provider versions and connection status, not credentials, project names, or conversations. Do not share your QR code or pairing code in a support message.

Stuck on a step? Open Mac setup troubleshooting. Once connected, follow Your first conversation.