Connect to your first Herdr host.

Prepare the host, add one verified SSH endpoint, test it without changing remote state, and open the work already running there.

Open the user guide

Before you begin

An Android device (opens in a new tab) with HerdRanger installed.
A Linux, macOS, or Windows host where Herdr (opens in a new tab) is already installed and usable by the SSH account.
Standard OpenSSH access using a password or supported private key.
A network path between phone and host. Prefer a private overlay such as Tailscale (opens in a new tab) or NetBird (opens in a new tab) when away from the same network.
A separate administrative path for recovery.

Current compatibility: this guide is reviewed for HerdRanger 0.10.0 and Herdr 0.9.0 / protocol 22. HerdRanger does not install Herdr, provider tools, users, VPNs, or firewall rules.

Prepare the host

Use a normal least-privilege account rather than root where practical. Sign in as that same account and confirm Herdr works:

herdr --version
herdr status
herdr session list --json
herdr api schema --json

If Herdr is stopped, start it through your normal host workflow. Do not publish its Unix socket or expose a TCP proxy to the internet.

Add the server profile

Open Servers and choose Add server.
Enter a display name, hostname or IP, SSH port (normally 22), and SSH username. Keep the username out of the host field.
Choose Password or Generate Ed25519 key. See Secure SSH setup before installing a generated key.
Optionally choose a preferred Herdr session and a default projects folder.
Save the profile, then choose Test connection or open it.

No agent provider is selected here. Provider choice belongs to each new chat.

Verify the SSH host fingerprint

The first connection shows the server’s SHA-256 SSH host-key fingerprint. Compare it with a value obtained independently from the host or its administrator. Choose Trust only when it matches.

If the host key changed, stop. A rebuild or restore may explain a change, but interception can also cause it. HerdRanger blocks changed keys and has no trust-anyway override.

Test, then open your work

Test connection checks SSH authentication, Herdr availability, protocol/schema compatibility, and the session query. It is read-only and closes the test connection afterward. Success does not prove that an agent provider is installed.

Open the server, choose a running session, open a space, and select an existing agent or start one. You can also select an automatically discovered project from the configured projects folder. That opens its existing space and agent when present; otherwise HerdRanger creates a space for the directory that already exists and starts the configured default agent. It never creates a new project directory.

Connection path: Android device → verified SSH → your host → Herdr local API/socket.