# How Herdr Remote Attach Works Over SSH: Architecture and Implementation

> Learn how Herdr remote attach works over SSH. Discover its architecture and implementation for seamless remote development and debugging. Explore the SSH tunnel and Unix socket bridge.

- Repository: [Can Celik/herdr](https://github.com/ogulcancelik/herdr)
- Tags: architecture
- Published: 2026-05-31

---

**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`](https://github.com/ogulcancelik/herdr/blob/main/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`](https://github.com/ogulcancelik/herdr/blob/main/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:

```bash
herdr --remote user@myhost

```

Use server-side keybindings instead of local configuration:

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

```

Preserve existing panes during reattachment with live handoff:

```bash
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`](https://github.com/ogulcancelik/herdr/blob/main/src/remote.rs)**: Core implementation containing `extract_remote_args`, `prepare_remote_herdr`, `SshStdioBridge`, and the `remote-client-bridge` command handler.
- **[`src/server/mod.rs`](https://github.com/ogulcancelik/herdr/blob/main/src/server/mod.rs)**: Defines `client_socket_path` used by the remote bridge to locate the server socket.
- **[`src/api/status.rs`](https://github.com/ogulcancelik/herdr/blob/main/src/api/status.rs)**: Implements the JSON status API consumed by `ensure_remote_server_ready` for version checking.
- **[`src/client/mod.rs`](https://github.com/ogulcancelik/herdr/blob/main/src/client/mod.rs)**: Local client entry point launched by `run_client_process`.
- **[`src/cli/server.rs`](https://github.com/ogulcancelik/herdr/blob/main/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.