Shepherdr

Home	Reader and files	Send keys
	Notifications

herdr, from your phone.

• never hunt for the stuck one — every terminal is marked working, blocked, idle, done, or unknown. when an agent needs you, shepherdr says so.
• open the exact terminal — read it, send text or shortcuts, and attach files while an agent is there. shepherdr never substitutes another pane.
• workspaces from the phone — create a workspace, add a worktree, close what's done, delete a clean checkout. herdr still does the work.
• notifications that mean something — blocked, done, or a trusted sign-in change. tap through to that terminal, or home if it's gone.
• passkeys, not accounts — trust this phone once. later visits are sign in with a passkey. no email, no password. a new browser cannot trust itself.
• private by default — loopback, then your tailnet. reaching shepherdr is never enough to trust a new device.

---

Install

Shepherdr needs Herdr 0.9.0 or later running locally, herdr on PATH, and the same OS account as Herdr. Herdr 0.9.0–0.9.1 are validated; newer or unknown versions run best effort with a warning.

Use matching Herdr CLI and server versions for terminal reads and control.

Download the archive for this machine from the latest release, plus its matching checksum file. The examples below use v0.4.2.

System	Archive
Linux x86-64	shepherdr_0.4.2_linux_amd64.tar.gz
Linux ARM64	shepherdr_0.4.2_linux_arm64.tar.gz
macOS Intel	shepherdr_0.4.2_darwin_amd64.tar.gz
macOS Apple silicon	shepherdr_0.4.2_darwin_arm64.tar.gz

macOS builds are unsigned. Expect a system warning on first run.

archive=shepherdr_0.4.2_linux_amd64.tar.gz
grep "  ${archive}$" shepherdr_0.4.2_checksums.txt | sha256sum -c -
tar -xzf "$archive"
mkdir -p "$HOME/.local/bin"
install -m 0755 "${archive%.tar.gz}/shepherdr" "$HOME/.local/bin/shepherdr"
shepherdr --version

On macOS, use shasum -a 256 -c - instead of sha256sum -c -. Put the binary on PATH if $HOME/.local/bin is not already there.

Go (embeds the browser app; release archives are still the usual path):

go install github.com/luiscleto/shepherdr@latest
# or pin a version: go install github.com/luiscleto/shepherdr@v0.4.2

From source — Go 1.27+, Node.js 20+, npm:

npm ci --prefix web
npm run build --prefix web
go build -o bin/shepherdr .

To upgrade to v0.4.2, update Herdr to at least 0.9.0 first. Stop Shepherdr, keep its state and configuration, replace the binary with the verified download, check shepherdr --version, then restart it.

Start

Start Herdr first. Shepherdr needs a stable private HTTPS address. Tailscale Serve is the usual way:

tailscale serve --bg 8787

Copy the printed address with no trailing slash, then:

shepherdr \
  -public-origin PRIVATE_HTTPS_ADDRESS \
  -vapid-contact mailto:you@example.com

-public-origin is https:// plus a lowercase DNS name, optional nondefault port. No path, no trailing slash, no :443. That address is saved and cannot be changed later.

First start prints a setup link and QR code. They expire in ten minutes and are not reprinted on restart. Miss them? Stop Shepherdr and run shepherdr access invite. Open the link, name the device, choose Trust this device.

Later starts

shepherdr

Open the same private address. Sign in with a passkey. http://127.0.0.1:8787 is only the local listen address.

Sign-in off (not recommended)

shepherdr -no-sign-in

Anyone who can reach Shepherdr has operator authority. The flag is not saved. Do not combine it with -public-origin or -session-lifetime.

Keep it private

Keep Shepherdr inside a network of people and devices you trust with the machine running Herdr.

• One private HTTPS hostname, only for Shepherdr. Open only that exact address.
• Passkeys are an extra lock, not permission to publish.
• No Tailscale Funnel, no public exposure.

When sign-in is on, do not open Shepherdr by loopback, IP, localhost, another name, or another port.

Devices

Settings → Devices lists trusted sign-ins, invites another device, revokes one while another remains, or signs this browser out. A passkey can sync; copies share one entry and are revoked together.

Stop Shepherdr first for local commands:

shepherdr access invite          # ten-minute link + QR
shepherdr access devices         # list trust IDs
shepherdr access revoke <id>     # refuses to remove the last passkey
shepherdr access reset           # wipe passkeys, sign-ins, invitations, notification subscriptions

Reset keeps the private address and notification contact. The next protected start prints a new setup invitation.

Notifications

Set a contact once. Each browser then chooses its own events under Settings.

shepherdr -vapid-contact mailto:you@example.com

An HTTPS website is also accepted.

On by default	Off by default
blocked, done, trusted sign-in added/removed	working, idle, unknown, workspace opened/closed

iPhone or iPad: add Shepherdr to the Home Screen and open it there before enabling. Android Chrome does not need that.

Reset (Shepherdr stopped):

shepherdr -reset-notifications

Best effort. No history, no delivery guarantee.

Terminal and files

On a phone, Terminal opens in Reader for reading and selecting output. The terminal icon beside Settings opens the full terminal for direct typing; tap its input area to open the keyboard. The phone icon returns to Reader, keeping your reading place, draft, and pending files.

Both views keep control until you release it or another controller takes over. Opening a terminal never takes control from someone else; taking over requires confirmation.

Send keys lets you choose Esc, Tab, Enter, Backspace, arrows, F1–F12, or one printable character, with Ctrl, Alt / Option, Shift, Super / Command, and Hyper. Herdr interprets the combination for the terminal. While observing, use Control or confirmed Take over first. Keys act immediately, independently of your unsent message and files. If the result is unknown, check the terminal before deliberately sending again.

Pin combinations without sending them, then edit, remove, reorder, or restore the shortcuts in this browser. Esc, Up, Down, Backspace, and Ctrl+C start pinned, in that order, with fixed Enter after the first shortcut. Saved choices stay unchanged; Restore defaults applies the new list. Tab remains in the picker and can be pinned. Enter, Send keys, control, and Message or Attach files remain available with their usual rules.

In Reader, Message opens the composer. Add files appears only while that exact terminal has a recognized agent. Photos and Files use the browser's ordinary pickers. Send submits the message and any selected file paths.

While a recognized agent is present, the full terminal's paperclip opens a compact files-only panel. Insert files adds local file references at the current cursor without pressing Enter. Submit them yourself when ready; your Reader message draft stays separate.

Shepherdr stores the files on this machine. Reader sends their absolute paths as:

User uploaded files:
- /absolute/path/to/file

Those paths are for the agent to open. They are not sent to a model.

Files stay with the workspace across agent changes and restarts. After the workspace is gone, Shepherdr tries to delete only the folder it created. Cleanup can fail. This is not file history.

Flags

Flag	Default	Notes
-listen	127.0.0.1:8787	Loopback only. Match this port with tailscale serve --bg.
-session-lifetime	30d	1d–365d, or none. Saved. Using Shepherdr does not extend it.
-herdr-socket	~/.config/herdr/herdr.sock	Uses $XDG_CONFIG_HOME/herdr/herdr.sock when nonempty, including on macOS. Pass an absolute path to override.
-log-level	info	Runtime logging: debug, info, warn, or error.
-upload-parent	system temp	Staging directory for selected files.
-upload-limit	50MiB	Per send. Bytes, KiB/MiB/GiB, or none.

Apache License 2.0.