Connect your computer

Set up the computer once, show its QR code, then scan it inside Handsfree. You do not need to type the long computer address or pairing code.

This guide follows the current mobile interface. The phone-shaped screenshots are real captures of the browser interface at iPhone size, using a disposable demo host. The installed iPhone app uses the same flow; its camera and permission screens are native iOS screens. The example QR below cannot connect to a real computer.

1. Start on the phone#

Open Handsfree. With no saved computer, you will see Bring your computer along.

• First time setting up the computer? Tap Set up my computer.
• Computer already running Handsfree? Tap Scan my computer’s code and jump to step 3.

The app on your phone is the remote control. The host is the Handsfree service on your computer. Installing the phone app or opening the website does not install that service.

If you open the development interface at localhost:8042 on the host Mac, it recognizes that it is on a computer, checks the standard local gateway on port 9879, and connects without a QR. The automatic path is loopback-only; remote browsers and phones still require normal pairing.

2. Get the computer ready#

Use your computer for this part. Open Set up your Mac & iPhone there and copy its opening setup request into your coding agent. That guide supplies the commands; this article shows what you should see along the way.

The completed setup should give you:

No desktop speech installation is needed: the iPhone recognizes speech and plays replies locally.

Keep the computer awake and online. The optional login service starts Handsfree when you log in; it does not prevent the computer from sleeping.

Already using a host from an older version? Update its checkout and dependencies before using the new QR helper. Restart it after active work finishes. Your setup's host upgrade and configuration notes also cover existing session stores.

3. Show the QR on the computer#

Once the host is running, open a terminal in the Handsfree repository on the computer. With the environment file from the setup guide, run:

node --env-file="$HOME/.handsfree-local/host.env" host/pair.mjs --url https://your-mac.your-tailnet.ts.net

Replace the example address with the exact private HTTPS address from your setup, without /health. If your setup used another environment file, use that file instead. This command opens a local page on the computer:

Leave your own page open. The QR contains the complete address, computer name and a short-lived pairing code. It does not contain your Claude credentials or the phone's lasting device token.

The helper remembers the address. To refresh an expired or used code later, run the shorter command on the same computer:

node --env-file="$HOME/.handsfree-local/host.env" host/pair.mjs

Each code works once and lasts ten minutes. Refreshing the code does not disconnect an already paired phone or stop accepted work. If your configuration sets HF_PUBLIC_URL, that setting takes precedence over the remembered address.

4. Scan inside Handsfree#

1. Connect the phone and computer to the private network or VPN used during setup. In the documented recipe, connect Tailscale on both devices.
2. Return to Handsfree on the phone and tap Scan my computer’s code, or Scan the QR shown on my computer from the setup screen.
3. Allow camera access, then point at the QR on your computer. The scan fills both connection fields and starts pairing automatically.
4. Wait for Hello, [your computer], then tap Let’s get to work.

Use the scanner inside Handsfree to pair the installed app. Scanning the same QR with the phone's ordinary Camera app opens the browser companion instead. That browser pairing is separate from the installed app's pairing.

Camera images are decoded on the phone, not uploaded. A QR scan supplies connection details; it does not create a VPN connection or wake a sleeping computer. You still need the private route established in step 2.

Pairing does not turn on the microphone. You will choose a session and tap Start talking separately.

If you need to enter details instead#

From the blank start, tap Enter an address and code instead. From the scanner, choose Enter details instead. Expand Enter details instead on the computer's QR page to find both values.

Enter the computer address without /health, paste the fresh code, optionally name the computer, and tap Connect computer. Use the host address, not ioshandsfree.vercel.app. On a physical phone, localhost and 127.0.0.1 refer to the phone itself.

Coming back or adding another computer#

The native iPhone app saves its pairing, so ordinary use does not require another scan. Open it, choose New session or Continue a session, and let it reconnect. Your computer still needs to be awake with Handsfree running. For the native-speech update, pull the current host code and restart it after active work finishes; older hosts show an update message in the iPhone app.

The browser companion keeps its pairing only while the app page remains loaded. Refreshing or closing that page requires a fresh code. Help now opens in a separate browser tab so reading an article preserves the original pairing; return to your original Handsfree tab afterwards.

For a second computer, tap Computers → Connect another computer and scan that computer's code. Enter connection details is the manual alternative.

Expand Connection details to inspect the address, disconnect, or forget a computer. Forgetting removes this client's saved pairing, so you will need a new code to reconnect it. It does not erase the project's files or the host's conversations.

If connecting gets stuck#

The operator troubleshooting table has the computer-side checks. When you reach the connected screen, continue to Your first conversation.