Herdr GPUI Connection Troubleshooting

A desktop connection failure can have several causes. Diagnose the daemon, the client, the coding agent, and remote access separately. This checklist gives you a sequence to follow without reinstalling unrelated components.

Herdr GPUI overview and setup builder

The application cannot find Herdr

Open an ordinary terminal and check the installed executable:

command -v herdr

If it is missing, follow the daemon installation guide. If it exists, record its location and your installation method. The native client documents discovery through PATH and standard installation locations, plus Terminal > Reconnect after installation.

The app can start an installed local server when needed; it does not install the daemon for you. Explicit socket and development targets have different behavior. Check the native-client documentation before changing a custom target.

The terminal connects, but an agent does not start

Check the command for the selected agent in an ordinary terminal. Confirm its own installation, authentication, and project access.

A login or model-access error belongs to that agent's setup. Installing the desktop interface does not supply credentials or account access. When the command starts successfully outside Herdr, compare the directory and environment used in the failing pane.

If only the displayed state seems wrong, inspect terminal output and the integration configuration. The supported-agent documentation explains detection and integrations. A blocked state may be a legitimate approval request rather than a connection error.

A remote machine does not connect

Verify your normal SSH access first, using the host you actually configured. Then check whether the remote machine has Herdr, the project, and the agent environment required for your task.

Distinguish an unreachable host, failed authentication, an untrusted host key, and an unavailable daemon. Changing your local GUI theme cannot fix any of those conditions.

Follow the Herdr remote-machine guide together with the native client's requirements. The GUI and the terminal interface do not have identical platform capabilities. In particular, the native client's documentation identifies platform-specific limits for saved SSH hosts.

Do not retry a coding job merely because its interface disconnected. Establish the connection and inspect existing terminal activity before deciding whether another job is needed.

The workspace returns, but a program is gone

A normal client detach can leave the daemon's processes running. A server or machine restart cannot preserve those original processes.

Layout recovery and supported agent-conversation restoration are different from restoring every shell, test runner, or server. Check what actually happened to the runtime, then consult session state and restore. A recreated pane is not evidence that the original program is still alive.

Preserve existing repository changes before restarting a task. Inspect saved progress and current output to avoid repeating work.

Fonts or themes do not behave as expected

Separate native-client preferences from shared Herdr settings. The client documents persistent overrides in config-gpui.local.toml and managed defaults in config-gpui.toml. Editing the managed defaults can be ineffective because the application replaces them.

Check the current configuration documentation before changing files. Record the specific setting and whether it affects the local interface or the selected remote environment. Make one relevant change at a time so you can tell what resolved the issue.

Prepare a useful issue report

Include your operating system, installation method, client version, daemon version, selected local or remote target, failing action, and exact error. State whether the executable exists and whether ordinary SSH or agent startup works.

Remove credentials, tokens, and private project content from logs. Do not describe an illustration on this website as evidence of a running session.

Return to the macOS setup guide for installation checks, or use separate agent worktrees once the connection is reliable.