Heeler Docs

Set up Heeler, an independent herdr mobile client for iPhone and iPad. Use Claude Code and Codex over SSH, with native Chat, notifications, and Usage widgets.

Heeler is an independent herdr mobile client for iPhone and iPad, connecting you to Claude Code, Codex, and other coding Agents over SSH. Agents run on your Host, the computer running herdr, rather than on your phone. Use these guides to connect a Host, send instructions in native Chat, and set up Usage widgets.

Explore Heeler for iPhone and iPad or download Heeler on the App Store.

New here?

With a Mac or Linux Host on the same network as your iPhone or iPad, such as the same Wi-Fi, the quickest start is to pair by scanning a code. Otherwise, follow the three steps below. If you are not sure which network to use, start with Tailscale.

Get started

Pair by scanning

Install the Heeler plugin, show a Pairing Code on the Host, and scan it. No form to fill in.

Set up by hand

Prepare the Host

On the Mac that runs herdr, install herdr, turn on Remote Login, note the Mac's SSH fingerprint, and choose how Heeler signs in: Prepare the Host. Going through a Jump Host? Skip the sign-in part; its guide sets up the key. For a Windows Host, follow Windows setup instead.

Choose how to reach it

On the same network, Heeler connects to the Mac directly. From anywhere else, use an overlay network such as Tailscale, or a Jump Host on a Debian or Ubuntu VPS that you run. A Host can have multiple routes, so it works both at home and away.

Add the Host in Heeler

Open Hosts, tap Add Host, and fill in the form (through a Jump Host, use these values). Tap Trust only if the fingerprint matches the one you noted; through a Jump Host, Heeler asks about the VPS first, then the Mac. Then verify the connection, including over cellular. Already paired? Add the Host's address on that network as another route instead.

Overlay networks

Heeler joins the network by itself, so your iPhone or iPad needs no VPN app. The Mac runs the provider's software.

Overview

Prepare the Host, pick a provider, and connect from Heeler.

Tailscale

Heeler joins your tailnet; the Mac runs the Tailscale app, or Tailscale from Terminal without a VPN. Start here if you are new.

ZeroTier

A private ZeroTier network; the Mac runs ZeroTier One.

EasyTier

No account needed. Away from home, it needs a relay or a Mac reachable from the internet.

Cloudflare Tunnel

Cloudflare's own app on the phone carries the connection, and the Mac opens no port. The phone runs a system VPN instead, so this suits people who would rather not run an overlay network.

Cloudflare Tunnel

A private network route with no domain, or a VPS running the tunnel client, then a Direct route in Heeler.

Jump Host

If you run a Debian or Ubuntu VPS, the Mac can keep a reverse SSH tunnel open to it, and Heeler connects through the VPS's normal SSH port. No overlay network or provider account is needed, and the Mac's SSH port is never exposed to the internet.

Set up a Jump Host

A copy-and-check walkthrough, one device at a time.

Jump Host in depth

The trust model, key rotation, and moving to a new VPS.

Hosts

Multiple routes

Give a Host its LAN address and a route for away; Heeler keeps the first that connects.

Windows setup

SSH login and automatic startup of SSH and herdr on Windows 11.

Fedora/RHEL SELinux

Let SSH open herdr's socket on Fedora, RHEL, and their derivatives when SELinux blocks it.

Chat

Use Claude Code and Codex on iPhone or iPad through native Chat. Read conversations, send instructions, and answer supported Agent questions with buttons instead of terminal keys.

Chat with an Agent

Open Chat, set up the Host for each program, send messages, and answer a Blocked Agent.

Troubleshooting

What each Chat message means and what to do about it.

Usage

See how close your Claude Code and Codex accounts are to their Usage Limits, and what your Agents used.

Usage and widgets

Read Usage Limits and Token Usage across Hosts, and keep them on the Home Screen and Lock Screen with widgets.
Edit on GitHub