How Herdr Remote Attach Works Over SSH: Architecture and Implementation

Herdr's remote attach feature establishes a bidirectional SSH tunnel that forwards local client I/O to a remote Herdr server through a temporary Unix socket bridge, automatically handling binary deployment, version negotiation, and live pane handoff.

The Herdr terminal multiplexer (ogulcancelik/herdr) enables seamless remote development through its remote attach capability over SSH. As implemented in the repository, this feature allows users to run a local Herdr client while the actual server process executes on a remote machine. Understanding how Herdr remote attach works over SSH reveals a sophisticated architecture involving automatic binary deployment, version compatibility checks, and transparent I/O forwarding through Unix domain sockets.

Parse Remote Connection Arguments

Remote attachment begins with argument extraction in src/remote.rs. The extract_remote_args function (lines 60-90) parses the --remote <target> flag and optional parameters including --remote-keybindings and --handoff.

This function returns a RemoteLaunch struct that encapsulates the target host, SSH configuration, and attachment preferences. The parsing logic validates the remote target format and prepares the connection context for the subsequent deployment phase.

Deploy the Remote Herdr Binary

Before establishing the connection, Herdr ensures the remote host has a compatible binary. The prepare_remote_herdr function (lines 92-124) orchestrates this deployment through several coordinated steps.

First, detect_remote_platform (lines 54-71) identifies the remote operating system and architecture by executing uname commands over SSH. If no matching Herdr binary exists on the remote host, the system downloads the appropriate release asset from GitHub. Users can override this behavior by setting the HERDR_REMOTE_BINARY environment variable to specify a custom binary path. The install_remote_herdr function (lines 59-68) then transfers the binary to the remote host via SCP or SSH-based streams, ensuring the executable has proper permissions for subsequent execution.

Negotiate Server Readiness and Compatibility

Once the binary is present, ensure_remote_server_ready (lines 153-174) verifies the remote server state by querying herdr status server --json. This check determines whether the remote server needs startup, restart, or live handoff based on protocol version mismatches.

If the remote server is running an incompatible version, Herdr can stop the existing instance or trigger a live handoff to preserve active pane sessions. The handoff mechanism requires the --handoff flag and ensures zero-downtime transitions when reconnecting to existing remote sessions.

Establish the SSH-Stdio Bridge

The core networking abstraction is the SshStdioBridge. When SshStdioBridge::start (lines 274-304) executes, it creates a temporary Unix domain socket on the local machine and spawns a listening thread.

For each incoming connection, the bridge_connection function (lines 339-389) spawns an SSH child process that executes herdr remote-client-bridge on the remote host. This establishes a secure channel where local socket data flows through SSH stdin/stdout to the remote bridge process. The bridge transparently handles encoding and buffering, ensuring low-latency terminal interaction even over high-latency connections.

Connect the Local Client to the Remote Server

With the bridge active, run_client_process (lines 410-428) launches a new Herdr client instance configured to connect to the temporary local Unix socket rather than a standard local server. This client believes it is communicating with a local Herdr instance, while actually transmitting all operations through the SSH tunnel.

On the remote side, run_remote_client_bridge (lines 82-106) connects to the remote server's client socket at crate::server::socket_paths::client_socket_path (defined in src/server/mod.rs). This function pipes stdin from the SSH channel directly to the remote server and streams responses back through stdout, completing the attachment circuit.

The data flow follows this path:

local terminal → local Herdr client → local Unix socket
                     ↓                        ↓
           SSH-Stdio Bridge ←────── SSH connection
                     ↓                        ↓
        herdr remote-client-bridge → remote Herdr server

Practical Usage Examples

Deploy the Herdr binary and attach to a remote server:

herdr --remote user@myhost

Use server-side keybindings instead of local configuration:

herdr --remote user@myhost --remote-keybindings server

Preserve existing panes during reattachment with live handoff:

herdr --remote user@myhost --handoff

Each command triggers the full pipeline: argument parsing, binary preparation, server readiness checks, bridge initialization, and client launch.

Key Implementation Files

The remote attach functionality spans several modules:

• src/remote.rs: Core implementation containing extract_remote_args, prepare_remote_herdr, SshStdioBridge, and the remote-client-bridge command handler.
• src/server/mod.rs: Defines client_socket_path used by the remote bridge to locate the server socket.
• src/api/status.rs: Implements the JSON status API consumed by ensure_remote_server_ready for version checking.
• src/client/mod.rs: Local client entry point launched by run_client_process.
• src/cli/server.rs: Remote server implementation started by the bridge process.

Summary

• Argument parsing in extract_remote_args handles --remote targets and optional flags like --handoff to configure the attachment session.
• Binary deployment through prepare_remote_herdr automatically downloads and installs the correct Herdr release for the remote platform, with override support via HERDR_REMOTE_BINARY.
• Version negotiation via ensure_remote_server_ready ensures protocol compatibility and supports live handoff to preserve active remote sessions.
• I/O bridging uses SshStdioBridge to create a temporary Unix socket that forwards traffic through SSH to herdr remote-client-bridge on the remote host.
• Transparent attachment allows the local client in run_client_process to operate as if connecting to a local server, while actually communicating with the remote instance.

Frequently Asked Questions

How does Herdr transfer the binary to the remote host?

Herdr uses the install_remote_herdr function (lines 59-68) to transfer the binary via SSH-based streams or SCP after detect_remote_platform identifies the correct architecture. The system checks GitHub releases for matching assets and can use a user-provided binary through the HERDR_REMOTE_BINARY environment variable.

What happens if the remote Herdr server version differs from the local client?

The ensure_remote_server_ready function (lines 153-174) queries the remote server status using herdr status server --json. If version or protocol mismatches are detected, Herdr either restarts the remote server or performs a live handoff when the --handoff flag is specified, ensuring compatibility before attaching the local client.

What is the purpose of the remote-client-bridge command?

The remote-client-bridge command, implemented in run_remote_client_bridge (lines 82-106), runs on the remote host to connect the SSH stdio stream to the remote Herdr server's Unix socket. This bridge process pipes input from the SSH channel to the server and returns output, effectively acting as a translation layer between the network stream and the local socket interface.

How does Herdr handle live pane handoff during remote attachment?

When the --handoff flag is provided, ensure_remote_server_ready negotiates a seamless transition where the new client connection takes over existing pane sessions without terminating them. This requires the remote server to support the handoff protocol and allows users to detach and reattach to remote sessions while preserving running process state.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}