---
title: Persistence and remote access
description: Detach from Herdr, reattach later, use named sessions, and connect over SSH.
---

Herdr keeps panes running in a background server. Your terminal client can detach and reconnect later.

For the local, SSH, and `herdr --remote` workflows, see [How to work with Herdr](/docs/how-to-work/).

## Detach and reattach

Start Herdr:

```bash
herdr
```

Detach the client with `ctrl+b q`.

Your panes and agents keep running. Reattach by running Herdr again:

```bash
herdr
```

If you want to end the session and stop its panes, stop the default server:

```bash
herdr server stop
```

## Named sessions

Use named sessions when you want independent Herdr servers.

```bash
herdr session list
herdr session attach work
herdr session attach side-project
herdr session stop work
herdr session delete side-project
```

A named session has its own panes, tabs, workspaces, sockets, and runtime state. It still shares the same global config file.

Use `--json` for scripts:

```bash
herdr session list --json
herdr session stop work --json
herdr session delete side-project --json
```

## Remote attach over SSH

Run Herdr on a server and attach from any SSH client:

```bash
ssh you@server
herdr
```

In this mode your shell is remote, Herdr runs on the remote host, and panes keep running there after you detach.

You can also attach through SSH from your local machine:

```bash
herdr --remote workbox
herdr --remote ssh://you@server:2222
```

In this mode your local Herdr is a thin client. It connects over SSH, starts or attaches to the remote Herdr server, and streams the UI back to your local terminal. Because the client runs locally, Herdr can bridge local desktop features such as image clipboard paste into the remote session by copying the image to a remote temp file and pasting that path.

For repeat targets, use your SSH config:

```text
Host workbox
  HostName server.example.com
  User you
  Port 2222
```

Then attach with:

```bash
herdr --remote workbox
```

Remote attach supports Linux and macOS hosts on x86_64 and aarch64. Herdr checks the remote platform, prefers a matching `herdr` already on the remote `PATH`, then checks `~/.local/bin/herdr`. If no matching binary exists, interactive runs prompt to install one to `~/.local/bin/herdr`; non-interactive runs fail instead of modifying the host. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install.

If you SSH into the server first and run `herdr` there, Herdr runs entirely on the server. That mode is useful and simple, but it cannot access your local desktop clipboard beyond normal terminal text paste.

When your local and remote platforms match, Herdr can copy the current local binary. Otherwise it downloads the matching release asset from `https://herdr.dev/latest.json`.

For local builds or custom binaries, set `HERDR_REMOTE_BINARY` to a local file path before running remote attach.

```bash
HERDR_REMOTE_BINARY=target/release/herdr herdr --remote workbox
```

## Remote named sessions

Use `--session` with `--remote` to attach to a named session on the remote host:

```bash
herdr --remote workbox --session agents
```

## Direct terminal attach

Full Herdr attach opens the whole workspace UI. Direct attach opens one server-owned terminal in your current terminal.

Attach by agent target:

```bash
herdr agent attach reviewer
```

Attach by terminal ID:

```bash
herdr terminal attach term_abc123
```

Direct attach streams the current rendered terminal state, then live ANSI frames. Input goes straight to that terminal.

Detach with `ctrl+b q`. Send a literal `ctrl+b` with `ctrl+b ctrl+b`.

Only one writable direct attach client owns input and resize for a terminal. Use `--takeover` to replace an existing owner:

```bash
herdr terminal attach term_abc123 --takeover
```

## Single-process escape hatch

Use `--no-session` to run Herdr without the background server/client split:

```bash
herdr --no-session
```

This is mainly an escape hatch for debugging or compatibility. The default persistent session mode is the normal path.
