Sessions

herdr-core

Install hc on your Mac or Linux host, connect from iPhone, and attach to an existing terminal in Shinphony. Includes detach, reconnect and troubleshooting.

You need a reachable SSH host and Shinphony on your iPhone or iPad. Attaching from the session list is free; Pro adds automatic re-attach. This guide uses macOS or Linux.

Use herdr-core, not the older TUI server

herdr-core (hc) runs terminals on your computer. The new Herdr desktop app is a front end for it. The older Herdr TUI has a separate server: its sessions do not appear as hc terminals.

Shinphony is an independent SSH client, not an official Herdr app or an AI service. Your coding tools and projects stay on your computer; install and sign in to those tools separately.

Install hc on your computer

Use the computer and account that own your project. Your shell, editor and coding tools run there; hc keeps their terminal available. If you use the new Herdr app, core may already be installed. Check before installing again:

hc --version
hc ls

If hc is missing, use the official macOS/Linux installer on that computer:

curl -fsSL https://releases.herdr.dev/core/install.sh | sh

This runs Herdr’s installer, not the Shinphony notification helper. You can read the script first. Follow its PATH instructions and open a new shell if hc is not found. The installer puts herdr-core in ~/.local/bin and only creates the hc command if that name is free. If another tool already owns hc, do not overwrite it: inspect command -v hc, the version and the installer output. Shinphony needs the correct hc command available to the SSH user.

In your project directory, create a practice terminal only if you need one. With no program specified, this starts the host’s default shell. --bg returns to your current shell without attaching:

hc run --bg --name phone-demo
hc ls

The list should now contain the terminal you created. Attach with hc attach phone-demo, check pwd, and start your own installed tool there if needed. Keep its name or returned address. If you already have a terminal for your project, use that instead; you do not need to move your task into a new shell.

Commands checked against the official README and command reference on November 9, 2026 (hc 0.1.19).

Attach from your iPhone

Use these details for the computer where hc ls shows your terminal:

SSH field	What to enter
Name	A label you recognize
Host	The computer’s address reachable from your phone
Port	Its SSH port, usually 22
Username	The same remote account that runs hc
Authentication	That account’s password or an already authorized private key

Connect to the same computer and user. Add or open its SSH server in Shinphony. Use the host address, SSH port (usually 22), the same username used for hc, and that account’s password or private key. Your phone needs a route to it, such as your local network or an existing VPN. Follow your first connection to verify the server’s host key.
Find the existing terminal. Open Remote sessions and look under hc. Select phone-demo, or the project terminal you found with hc ls. Attaching from the list is free; automatic re-attach is part of Pro.
Continue on the host. You are now in that terminal. Try pwd or read the existing output to check your working directory before continuing.

You can also attach manually from a plain SSH shell. Basic SSH remains free:

hc ls
hc attach phone-demo

Use your terminal’s actual name or address from the list. An example address in someone else’s guide is not your terminal. Compare pwd and the existing output with the computer before sending more input; reconnecting should not mean starting a second copy of your task.

Detach, then return to the same work

Herdr-core’s detach key is Ctrl+\ (Control and backslash). Use your keyboard or terminal key controls to send it. Detaching leaves the terminal running. Typing exit or killing the program ends it instead.

iOS may suspend your SSH connection when you leave the app. Reconnect and select the same hc terminal, or use hc attach again. With Pro, automatic re-attach returns you without picking it each time.

The terminal runs on your computer, not your phone. Disconnecting the phone is different from rebooting the computer or ending the program; this does not promise to restore an agent’s work after a reboot.

Keep files and feedback close to the terminal

Use screenshot attachments to show your agent what to change, then preview an HTTP development site through SSH. Screenshot editing and terminal attachments require Pro. Ordinary SFTP transfers and HTTP web preview are free. The agent must support reading the uploaded image.

Set up Shinphony Hook (optional)

Shinphony Hook is the notification component installed on your own computer. herdr-core keeps terminals running; Hook reports supported task events to your phone. You can use SSH and hc without it. Basic task notifications and Live Activities are free; Pro adds higher limits.

Open the host’s notification setup. Connect to that server in Shinphony. In the terminal tab’s More menu, choose Task notifications.
Enable and review. Allow notification permission, choose Set up notifications, and review the host service, agent hooks, signed updates and terminal-preview disclosure before accepting. Keep the app foregrounded and SSH connected until the host accepts setup.
Trust the installed Hook. Once setup completes, start or resume a supported agent session on the host and review its Shinphony Hook trust prompt.
Check, then test delivery. Use Check status before retrying an interrupted setup. For a deliberate completion test, ask the supported agent to use its installed notification skill, then background Shinphony and check that the alert actually arrives. Setup acceptance alone is not delivery. Use Show on Lock Screen for a Live Activity.

The complete Shinphony Hook setup guide covers permissions, test requests and removal. Its current rich-context route is tmux + Codex on macOS/Linux; this does not promise exact return or question replies for every hc terminal. Read Shinphony Hook reference for updates and what is sent.

hc and tmux can run on the same host, but their sessions are separate. Upstream hc also has Windows x86-64 builds; this guide covers Mac/Linux and does not claim equivalent Shinphony integrations or notifications on Windows.

If the terminal does not appear

SSH is unreachable or the fingerprint changed

Check the host, port and phone’s network route. For an unexpected host-key change, stop and verify with the administrator or trusted console; do not bypass the warning to reach the session list.

No hc section or an empty list

Confirm the phone uses the same SSH host and user. In that SSH environment, run command -v hc, hc --version and hc ls. Confirm it is herdr-core rather than an unrelated command named hc; the interactive computer shell and SSH environment can have different PATH values. Check the installer’s PATH instructions, whether a terminal is actually running, and whether you started it in the older Herdr TUI or tmux instead of core. Keep any actual error message when asking for help.

“registry writer stopped”

Record the hc version and error. The current official command reference documents hc server restart to restart core while programs keep running. This is not a host reboot or hc server stop. Use it for this reported error, not as a first step for every empty list.

The phone disconnected

Reconnect and select the existing terminal. An iOS disconnect does not by itself end a core terminal. If the program exited or the host rebooted, do not expect the same running process to come back.

For the product overview, see herdr-core on iPhone and iPad. For prices and restoring a purchase, see Pricing and Pro.

Current App Store release: 1.1.0 · Updated 2026-11-09

Next →tmux