Your projects, within reach.

What you need

Use iOS 17 or iPadOS 17 or later, an awake workstation or self-hosted server running Herdr, and the companion Herdr Remote host. The runner can also live in a configured container. Herdr 0.9.5 is recommended for the complete action set; older versions may expose fewer capabilities. The host needs OpenSSL for initial certificate setup, and Bun when run from source rather than a standalone executable.

Your phone needs a reachable private-network, app-only WireGuard, secure gateway or raw TCP relay route. The app does not configure your router, wake a sleeping runner or provide a hosted AI account. Herdr owns the terminal and agent processes on the runner. Configure your coding agents and model access there; provider accounts and any usage charges are separate. The app has no subscription or in-app purchase.

Pair a computer

On the same Wi-Fi, the quickest way is herdr-remote up on the computer: it appears in the app under On this network, and tapping Pair shows a 6-digit code on the computer to type on the phone. Check that the fingerprint matches on both screens. Otherwise, use a QR invitation:

1. Initialize and start the companion host with an HTTPS address that your phone can reach. Keep its private state on that computer.
2. In another terminal on the same computer, run herdr-remote pair --scope control --qr. Choose a read-scoped invitation when the device should only inspect work.
3. In the app, choose Pair a computer. Scan the QR code or paste its invitation, check the host address and connection method, choose a device name and pair. Use the invitation’s supplied route by default.
4. Open Projects, choose a session or pane, and inspect its activity. Request Take control only when you want to send terminal input.

Invitations normally expire after five minutes and can be used once. Create a fresh invitation if one expires or was already consumed. Pairing QR codes and invitation text are temporary secrets; do not share them in support requests.

Private access and gateways

On the same network or an existing phone VPN, use a directly reachable host address. For app-only WireGuard, use an invitation containing the profile, or open Connection options while pairing and import a single-peer WireGuard configuration. The invitation must identify the runner’s private tunnel IP and port, and the profile must permit that destination. This routes only the app; it does not enable a phone-wide VPN or change another app’s connection.

For an HTTPS reverse proxy or Cloudflare Tunnel, the host operator can provide an authenticated secure-gateway invitation. A gateway token is separate from the app’s paired-device credential. Supported outer access methods include configured Basic authentication and Cloudflare Access service tokens; interactive browser sign-in and redirects are not supported. Ask the operator for an app-compatible invitation.

The gateway forwards the runner’s separately encrypted TLS connection. The reverse proxy can terminate the outer gateway HTTPS connection without replacing the paired runner certificate. A raw TCP relay instead forwards that runner connection directly. Neither relay mode creates terminals or starts agents; a runner is required behind it. WireGuard needs a reachable UDP endpoint. Port and tunnel setup remain under the host operator’s control.

For a computer behind NAT or a work firewall, the bridge can instead dial out to a reverse relay you run, so the computer needs no inbound port. Join the relay on the computer, then pair with a fresh QR invitation, which carries the relay route. See Reach it from anywhere.

Keep the app in the foreground for live access. After about 20 seconds in the background the app releases terminal control and closes app-only routes; reopening reconnects where you were.

If a connection fails

Check that the computer is awake, Herdr and the companion host are running, and the phone can reach the configured address. Wi-Fi and cellular may need different network access. Check that the selected WireGuard UDP endpoint or secure-gateway address is reachable, and that gateway or reverse-proxy credentials are still valid. A browser login page is not a compatible gateway connection.

If the host certificate changed or expired, follow the host’s certificate-replacement procedure and pair again. Do not turn off certificate validation to recover access. If access was revoked, obtain a new invitation from the host operator.

Observation, control and delivery

Opening a pane observes it. Take control requests a short control lease; taking over another controller is a separate action. Release control when you finish. The app releases its lease when backgrounded and does not automatically reclaim it when reconnecting.

An accepted command means the host admitted input, not that an agent completed the task. If delivery is unknown, check the terminal and Command delivery in Connections before issuing another command. The app does not automatically resend uncertain input. The host’s operation journal is bounded and is not automatically pruned; if it reaches its limit, preserve unresolved delivery evidence before following the host operator’s maintenance instructions.

Terminal control has the authority of the computer’s user account. Test creation, splits and pane closure in a disposable project first; closing a pane terminates its running program.

Voice notes

Tap the microphone in the message box, or Voice note in the prompt draft, choose a speech language, and grant microphone and speech permission when prompted. Stop when finished: the note is transcribed on the device and added to your draft. Review or edit it, then send it with control of the intended pane. Nothing is sent automatically.

Transcription is on-device only. If your device or language does not support it, choose another language or type the prompt; there is no silent cloud fallback. The system keyboard’s own microphone is separate and follows your iOS dictation settings.

History, files and changes

Conversation history is available only when the host can bind the pane to a supported native agent session. Other panes still provide terminal output. Large histories and previews are bounded; the app reports omitted or unavailable content rather than promising every agent format.

File and Git inspection requires a trustworthy project root. Ignored files and sensitive paths can be excluded, and binary or oversized previews may be unavailable. This does not change what your terminal commands can access on the computer.

Forget or revoke a device

In Connections, swipe a saved computer and choose Forget to remove its local credential. Keychain credentials may survive uninstalling the app, so forget first when you want the local record removed. Use the host’s device list and revoke command for a lost device or to end server-side access. If that device also had a WireGuard peer or gateway credential, revoke those separately with the corresponding network operator. Forgetting a local record is not remote revocation.

About background alerts

The current standard distribution does not provide a public background notification service. The core app works without it. Separately configured developer notification modules do not make every beta build notification-ready, and iOS does not keep arbitrary terminal sockets running indefinitely in the background.

Tell us what happened

Email the app version and build, your device and OS version, the host and Herdr versions, what you did, and the result you expected. TestFlight feedback is also useful during beta testing. You can read how optional correspondence is handled in the app privacy policy.

Do not include API keys, passwords, live QR codes or invitation text, device tokens, WireGuard profiles or private keys, gateway/access credentials, TLS private keys, or private code and terminal contents. Redact screenshots and logs before sending them.

AI Agent Remote is an independent companion project, not an official Herdr application.