HANDSFREE / HEADLESS LINUX

A server. An iPhone.
A little more freedom.

This private setup page is forwarded over SSH. Keep the setup link secret. No Linux desktop is needed.

START HERE

Unlock this host

Create a vault passphrase the first time. Save it in your password manager: you’ll need it after restarting Handsfree. It encrypts your Handsfree account credentials on this server.

Vault passphrase (at least 12 characters)Confirm new passphrase

Forgotten passphrases cannot be recovered. Don’t delete the vault: ask your administrator to help preserve your host data.

1 / YOUR ACCOUNT

One account for your devices.

Use this same account on your iPhone. This internal preview uses Clerk Development. Your SSH tunnel must also forward port 43821 for the browser callback.

2 / PRIVATE NETWORK

Connect with Tailscale.

Install Tailscale on this Linux machine and your iPhone, and connect them to the same tailnet. Handsfree uses private HTTPS; leave public Funnel sharing off.

Linux install instructions ↗

3 / CODING AGENTS

Bring your agent.

Install and authenticate the CLI on this Linux machine, as the same Linux user running Handsfree. A login on your laptop doesn’t authenticate this server.

For an agent login on a headless server, follow the provider’s remote-login instructions in its official setup guide. The vault protects Handsfree credentials; the provider manages its own credentials.

Enable Claude CodeAllow agents to read, change files, and run commands as this Linux user. Project selection is not an operating-system sandbox.

Codex installation, login, and runtime checks are available. Codex phone execution is not enabled in this release.

4 / PROJECTS

Choose where you’ll work.

Linux search folders, one absolute path per line

Leave blank to search common project folders. Scanning is read-only, bounded, and skips dependencies and hidden folders. Git worktrees are supported.

Add a folder that isn’t a Git repository

5 / YOUR IPHONE

Bring it together.

Install the internal iPhone build from TestFlight (ask Todd for access), sign in with the same Handsfree account, and turn on Tailscale. In Handsfree, choose Add computer and scan this host’s code.

iPhone setup & account help ↗

Closing this browser or your SSH tunnel does not stop a service-installed host. Restarting Handsfree locks the vault and stops the host until you unlock and start it again.

Diagnostics

Review your iPhone’s recognized words, matched keywords and decisions. History belongs to your signed-in account, with no global utterance feed. Requires iPhone build 26 for automatic capture; build 25 uses manual capture.

Voice history contains transcripts. Connection diagnostics contain no speech text or credentials. Voice history keeps the latest 1,000 events for up to seven days; review, export and delete it while your host is running.