Connection & troubleshooting

Your phone is the conversation. Your computer does the work.

Let your coding agent set it up

Open the Handsfree repository on your Mac and paste the request below into your coding agent. The complete local setup guide includes commands for automatic startup, private HTTPS through Tailscale, pairing and troubleshooting.

Set up this Handsfree checkout so I can test the real app on my iPhone.
Read docs/LOCAL-SETUP.md and host/README.md, and follow the agent handoff there.
Inspect existing services and Tailscale routes first; reuse a healthy setup.
I authorize local dependency installation, a real Claude host,
a user login service, and private HTTPS using Tailscale Serve.
Start in a disposable project. I understand unattended Claude tools run as my
OS user and allowed project roots are not a filesystem sandbox.
Keep credentials and logs outside Git. Help me connect both devices to the same
Tailscale account, leaving login, consent and OS prompts for me.
Use native iPhone speech; no desktop speech installation is needed.
Verify real Claude and the clientSpeech.v1 capability, then the actual HTTPS/WSS route. Give me the exact
host URL, open a QR with host/pair.mjs, and give me its refresh command plus
start/stop instructions. Configure named project choices with HF_PROJECTS.
Walk me through phone health, text and voice tests. Do not deploy the website.

1. Set up your host

Handsfree connects to a gateway running on your trusted computer, with access to your projects and a configured Claude agent. Install and configure the host from the Handsfree repository, following its host setup guide. Keep provider credentials on that computer.

The host needs a trusted HTTPS certificate and a network route from your phone, such as your private network or VPN. A website deployment by itself does not run the agent.

Connect from your phone tonight

Before pairing, make sure you have a running host, a trusted HTTPS address for it, and a network route from the phone. The public Handsfree website supplies the interface; it does not create or relay a host connection.

1. On your computer, install the host dependencies with npm ci inside the host folder. Configure your Claude login, project directory, and execution permissions using the host README. Start both the daemon and gateway using the supplied run.mjs supervisor or your existing service setup.
2. Keep the gateway on 127.0.0.1:9879 behind a private HTTPS reverse proxy, or bind it to a private interface with TLS_CERT and TLS_KEY. The certificate must be trusted by your phone and match the hostname. The proxy must forward /pair and WebSocket upgrades at /ws.
3. Connect your phone to the same private network or VPN. An option is Tailscale Serve, which shares a local service over your tailnet and requires HTTPS certificates. Keep access limited to your devices; do not turn on a public tunnel for this setup.
4. From the phone’s browser, open your host’s HTTPS address followed by /health. You should see a small JSON health response without a certificate warning. If this fails, fix routing, DNS, or TLS before trying a pairing code.

Use the computer’s reachable HTTPS hostname in Handsfree. localhost and 127.0.0.1 on a physical phone refer to the phone itself. They are useful for local development and simulator testing, not for reaching your computer from an iPhone.

Using the hosted browser companion

Add this exact origin to the gateway environment before starting or restarting it:

HF_ALLOWED_ORIGINS=https://ioshandsfree.vercel.app

This authorizes the companion page to make browser requests to your paired gateway. Device pairing and authentication are still required. If you use a different companion domain, explicitly allow that domain instead. The native app uses its own transport and does not need a browser CORS origin.

Some browsers also ask for permission to connect to devices on your local network. Allow it for the companion if you want that connection; if you declined, review the site’s Local Network Access setting. Chrome documents this in its Local Network Access guide. This permission is separate from microphone access.

Keep the browser page open and in the foreground for voice. After a page reload, pair again with a fresh single-use code. A real voice conversation also needs working transcription on the host; demo mode’s transcript and agent replies are explicitly simulated.

2. Pair your device

On your computer, use the QR pairing command to open a fresh connection code. In Handsfree, choose Scan my computer’s code. Scanning fills the address and one-use code and connects automatically. Enter details instead is available if the camera cannot scan. Refresh an expired or used code by rerunning the desktop command.

On iPhone, the device credential is stored in Keychain. The browser companion keeps its credential only in page memory, so pair again after reloading. Removing a host from the app removes its local pairing; revoke a lost device’s credential on the host.

3. Open a session

Choose New session, then your computer, project and agent. Steps with one available option are skipped. Check the selected project and tap Start talking, or Type instead. To resume, choose Continue a session and a recent conversation.

Allow Microphone and Speech Recognition access when asked. iPhone also needs local network permission for a LAN host. The browser requires HTTPS or localhost and must remain in the foreground for voice. Keep the iPhone app open while talking; it keeps the screen awake. Leaving the app pauses listening. The iPhone uses on-device English recognition and its own voice. Browser voice uses optional host speech services.

Keep the conversation under your control

• Record once: begin recording; tap Finish recording to send it for transcription.
• Start talking / Pause listening: start continuous listening or pause capture.
• Stop speaking: silence playback without canceling agent work.
• Stop agent: ask the host to interrupt the current turn and clear its pending queue.
• Replay reply: hear the most recent assistant response again.

Done for now stops listening and playback and returns home. Accepted work continues on the computer. Leaving an unfinished single recording discards it.

If a connection drops

The app reconnects automatically. Accepted work can continue on the host while your phone is disconnected. Microphone audio is not held for later submission during a long disconnect. If the host itself crashes, an active job may have an interrupted or unknown outcome. Review the host and project before retrying an action that changes files or external systems.

Need to troubleshoot?

Check that the gateway is running, the certificate is trusted, and your phone can reach the host address. A rejected device credential needs a fresh pairing. For microphone errors, check the app’s permissions in iPhone Settings or your browser’s site settings. Text commands remain available without microphone permission.

This is a developer beta. Report issues through the repository or the support contact provided with your build. Include the app version, device and OS, steps to reproduce, and the visible error. Do not include pairing codes, device tokens, provider keys, or private project contents.