# SSH transport

> For AI agents: the full Nearhost documentation index is at https://nearhost.dev/llms.txt. Every docs page is also available as Markdown: replace the trailing slash with `.md`, so https://nearhost.dev/docs/getting-started/install/ becomes https://nearhost.dev/docs/getting-started/install.md.

How Nearhost drives OpenSSH with one supervised control master per server, or on Windows one ssh.exe per forward.

Nearhost shells out to OpenSSH, so your `ssh_config` applies. If `ssh <host>` works without a prompt, Nearhost works.

## One master per server

Each remote server gets one OpenSSH ControlMaster process, supervised by Nearhost and started when a project there first needs it:

```sh
ssh -N -M -S ~/.config/nearhost/run/<server>.sock \
    -o BatchMode=yes -o ExitOnForwardFailure=yes \
    -o ServerAliveInterval=15 -o ServerAliveCountMax=3 \
    -o ControlPersist=no -o ClearAllForwardings=yes \
    -o RemoteCommand=none -- <host>
```

The control socket is in `run/` in Nearhost's config folder. The example shows the default, `~/.config/nearhost`; with an absolute `XDG_CONFIG_HOME`, it is `$XDG_CONFIG_HOME/nearhost/run` instead. When the socket's path would be too long for a Unix socket, it is named `h-<hash>.sock`.

The last three options keep the master to Nearhost's own forwards: `LocalForward` and `RemoteForward` lines in your config are left out, and a `RemoteCommand` is not run. The `local` server needs no transport.

Discovery and the add forms open a separate connection of their own, so reading a project's files never disturbs a running one.

## Forwards added live

Forwards are added and removed on the running master, with no reconnect:

```sh
ssh -S <sock> -O forward -L 127.0.0.1:<local>:localhost:<remote> -- <host>
ssh -S <sock> -O cancel -L 127.0.0.1:<local>:localhost:<remote> -- <host>
```

The forward always listens on `127.0.0.1`. From Nearhost 0.7.0, a `loopback` route also gets a relay that Nearhost runs on `[::1]:<port>` and passes to that forward, so the port answers on both loopback addresses. On a machine without the IPv6 loopback, it answers on `127.0.0.1` only. A program already listening on `[::1]:<port>` counts as holding the port.

[Forward several ports over SSH without retyping -L](https://nearhost.dev/docs/guides/forward-ports-over-ssh.md) compares this with the ways to do it by hand.

Nearhost keeps the list of forwards each server should have. After a reconnect it puts them all back before the server shows as connected. A forward that fails, because something on your laptop holds the port, puts its project in `error` with the name of the program.

## The agent socket

Each master also forwards a Unix socket back to the laptop, at `~/.nearhost/<id>.sock` on the server, so that a coding agent there reaches Nearhost. It is added after the master connects and again after each reconnect, and a server that refuses it only loses that: its projects serve as usual. See [How agents reach Nearhost](https://nearhost.dev/docs/coding-agents/how-it-works.md).

## On Windows

The OpenSSH client in Windows, `ssh.exe`, has no connection sharing: no ControlMaster and no `-O` commands. So on Windows, Nearhost runs one long-lived `ssh.exe -N` per server for the connection and the agent socket, and one more `ssh.exe` for each forward, started when the project or browser preview needs it and stopped when it no longer does. Reading files over SFTP opens a short connection of its own. Starting or stopping one project never touches another project's forwards. Each of these `ssh.exe` processes logs in on its own, so a key that needs a touch or an approval at each login asks once for each forward, and again for each forward every time the server reconnects. Each `ssh.exe` runs with `BatchMode=yes`, `ExitOnForwardFailure=yes` and the same keepalives as above, and your `~/.ssh/config` applies as it does on macOS and Linux, with one limit. Without a control master, Nearhost cannot keep your config's own forwards out of its connections, so the `Host` entry it uses for a server must not set `LocalForward`, `RemoteForward`, `DynamicForward`, `ForkAfterAuthentication yes` or `ClearAllForwardings yes`. If it does, Nearhost stops connecting to that server and names the setting. Move those lines to a `Host` entry Nearhost does not use, such as another alias for the same machine.

`ssh.exe` cannot forward a server's socket to a Unix socket on the laptop, so the agent socket on the server leads to a port on the laptop's loopback address instead. Nearhost answers there only requests that carry a token, which it writes beside the socket on the server, readable only by your account. See [Agents and Windows laptops](https://nearhost.dev/docs/coding-agents/how-it-works.md#windows-laptops).

Reconnection and backoff below work the same way on every system.

## Reconnection and backoff

If the master exits, Nearhost starts it again, waiting 1 second, then twice as long each time, up to 30 seconds. A master that does not connect within 20 seconds is stopped and tried again. While it waits, the server shows `reconnecting · attempt 3 · next in 8s`, and its projects show `degraded`.

Some errors do not go away by retrying: `Permission denied`, a host key that failed or changed, and too many authentication failures. After three of those in a row, Nearhost stops and the server shows `auth failed`, with the fix: run `ssh <host>` once in a terminal, then press `r`.

## Reconnecting and dropping

On a server's row in the interface:

- `r` reconnects now, without waiting for the next attempt. On Home, `r` does this for every server that cannot connect.
- `c` drops the connection and holds it closed. Its projects keep their sites and show `degraded`, and starting one there is refused until you press `c` again to connect.

## Shutting down

On exit, Nearhost stops every master with `-O exit`, and stops it outright if it has not gone after 3 seconds. On Windows it stops each `ssh.exe`. A socket left by a crash is checked before each start, and cleared.

## What is stored

Nothing beyond the host string. No keys, passwords or sockets are kept in `config.yaml`.
