herdr-mirror

A herdr plugin that mirrors a remote herdr server's workspaces and agents into your local sidebar. One window shows the agents on every machine — blocked, working, done — with live pane content you can watch and drive.

Each remote workspace becomes a real local workspace named <host>: <name>. Its panes stream the remote terminal live; its agents report their real state. Mirroring is one-way (the remote needs no plugin — just herdr), but you can type into any mirror pane to drive the remote session, and create remote workspaces/tabs/panes from your side.

A remote can be another machine over ssh, or a container on this one (see Devcontainer) — same mirrors either way.

How it works. One Rust binary (herdr-mirror) with subcommand modes: a daemon (control plane — reconciles remote workspaces into local mirrors and pushes agent status) and one pane process per mirror pane (data plane — streams the remote terminal).

Requirements

• Both ends: herdr with the terminal session streams — preview build 2026-06-30 or newer (herdr channel set preview), until the next stable.
• Local machine: macOS or Linux on x86_64/aarch64 — install fetches the prebuilt binary from Releases (dev installs via herdr plugin link build from source with cargo build --release).
• ssh hosts: non-interactive key auth to each remote (ssh -o BatchMode=yes <host> true must succeed without a prompt).
• Container hosts: a working docker CLI, plus socat and herdr inside the image. No sshd, no keys, no published ports.

Installation

herdr plugin install nikok6/herdr-mirror     # or: herdr plugin link <path>
herdr server reload-config                   # load the plugin (actions + autostart hook)

Then create the config at ~/.config/herdr-mirror/hosts.toml:

[hosts.work]
target = "work"        # anything ssh accepts: alias, user@host, ssh://host:2222

That's it — the daemon autostarts when you focus a workspace, so within a few seconds work: * workspaces appear in your sidebar. Check state any time with herdr-mirror status, which prints the config file it loaded.

Config location. ~/.config/herdr-mirror/hosts.toml is the canonical path: it's the only one reachable from both plugin actions and a plain shell. The plugin config dir (herdr plugin config-dir mirror) is also searched and takes precedence if a hosts.toml lives there, but prefer the canonical path unless you have a reason not to. If both exist, the ignored one is reported rather than silently dropped.

If you've disabled autostart, start the daemon yourself by keybinding the "Mirror: start" action or running:

./target/release/herdr-mirror start

Usage

Drive — the default (always_control = true) is tuned for headless remotes (a vps, a server) with no window of their own: it keeps each mirror pane writable and sized to your local pane, so the headless remote fills it instead of showing a tiny default-sized window. Type and your keystrokes go to the remote, tmux-style; the mouse wheel scrolls remote scrollback.

Watch-only — for a machine with its own display or a human sitting at it, set always_control = false (globally or per host). Its mirrors become read-only: a live view with zero effect on the remote that escalates to control when you type and auto-releases after 1h idle (ctrl+\ releases immediately).

Close / restore — by default, closing a mirror (prefix+x) also closes the pane/workspace on the remote (close_remote_on_local_close; set it false to only stop mirroring and leave the remote — and its agent — running). When the remote is left running, the restore action (herdr-mirror restore) brings back mirrors you closed.

Pause — the pause action halts syncing; mirrors stay frozen in place and resume with start. teardown closes all mirrors and clears state.

Create on the remote — four actions create objects on the remote host, inheriting the target host and cwd from the mirror you invoke them from (the same rule as native prefix+shift+n, but remote): remote-new-workspace, remote-new-tab, remote-split-right, remote-split-down. The new object mirrors back within seconds.

Continuous streaming — every mirror pane streams its remote pane live for its whole lifetime, each over its own connection, so panes are never blank and a busy pane can't contend with or drop another's stream. Sidebar agent status is daemon-driven, not stream-derived, so every agent's state stays live regardless of what any stream is doing.

Keybinds

Actions have no default keys; bind them in ~/.config/herdr/config.toml, then herdr server reload-config:

[[keys.command]]
key = "prefix+shift+m"
type = "plugin_action"
command = "mirror.start"       # start / resume the daemon

[[keys.command]]
key = "prefix+shift+s"
type = "plugin_action"
command = "mirror.pause"       # freeze syncing; start again to resume

[[keys.command]]
key = "prefix+shift+b"         # "bring back" (shift+r is native reload_config)
type = "plugin_action"
command = "mirror.restore"     # un-close mirrors you closed locally

[[keys.command]]
key = "prefix+alt+d"           # destructive: closes ALL mirrors + clears state
type = "plugin_action"
command = "mirror.teardown"    # stop mirroring everything (start to resume)

# Create objects on the REMOTE host — run these from inside a mirror pane, which
# supplies the target host and cwd. Each is herdr's native local key + alt
# (Option): same muscle memory, but it acts on the remote host.
[[keys.command]]
key = "prefix+alt+n"           # native new_workspace = prefix+shift+n
type = "plugin_action"
command = "mirror.remote-new-workspace"

[[keys.command]]
key = "prefix+alt+c"           # native new_tab = prefix+c
type = "plugin_action"
command = "mirror.remote-new-tab"

[[keys.command]]
key = "prefix+alt+v"           # native split_vertical = prefix+v
type = "plugin_action"
command = "mirror.remote-split-right"

[[keys.command]]
key = "prefix+alt+minus"       # native split_horizontal = prefix+minus
type = "plugin_action"
command = "mirror.remote-split-down"

The remote-* actions need a focused mirror pane (except remote-new-workspace, which falls back to default_host when run outside one). The remaining actions — mirror.status, mirror.once, mirror.teardown, mirror.ensure — are lifecycle/diagnostic and are usually run from the CLI rather than bound.

Mouse

Mirror panes adapt to what's running on the remote pane:

• at a shell, the mouse stays local — drag-select and copy work natively, and nothing leaks into the prompt;
• in a TUI (vim, htop, lazygit, …), clicks and wheel forward to the app.

herdr's streamed frames don't carry the app's mouse mode, so the plugin infers it from the remote pane's foreground process — anything that isn't a known shell is treated as a mouse-aware TUI. Detection is polled, so after switching between a shell and a TUI there's a brief lag before the mouse mode catches up.

Configuration

hosts.toml:

# autostart = true       # focusing a workspace starts the daemon (default).
                         # A manual pause is sticky until you start again;
                         # a crash still auto-recovers on next focus.
# poll_seconds = 60      # reconcile poll interval (events drive most syncs)
# default_host = "work"  # host that "new remote workspace" targets when
                         # invoked outside any mirror (default: first host)
# close_remote_on_local_close = true
                         # default. Closing a mirror pane/workspace locally
                         # (e.g. prefix+x) also closes it on the remote. Set
                         # false to only stop mirroring on a local close,
                         # leaving the remote pane and its agent running.
# always_control = true  # default. Mirror panes stay in control: writable, no
                         # idle release, and sized to your local pane so the
                         # remote fills it (ideal for headless remotes). Set
                         # false for read-only mirrors that escalate on type.

[hosts.work]
target = "work"
# prefix = "work"                    # sidebar prefix (default: the host key)
# remote_bin = "~/.local/bin/herdr"  # remote path if it's not on the remote PATH
# always_control = false             # per-host override, e.g. a host you use
                                     # directly (don't drive its pane sizes)
# enabled = true                     # false stops syncing this host without
                                     # deleting its config; mirrors stay put

[hosts.vps]                          # add more hosts freely; each is independent
target = "ssh://niko@203.0.113.7:2222"

Devcontainer

A herdr server running inside a container mirrors like any other host, reached over docker exec instead of ssh. Nothing is installed into the container and no port is published:

[hosts.dev]
kind = "docker"
folder = "/Users/you/code/my-project"   # devcontainer.local_folder label

# container = "my-container"            # ...or pin an explicit name instead
# docker_bin = "/usr/local/bin/docker"  # if docker isn't on the daemon's PATH
# remote_bin = "~/.local/bin/herdr"     # default; resolves inside the container,
                                        # so only set it if herdr lives elsewhere
# prefix = "dev"                        # sidebar prefix (default: the host key)

Resolve by folder, not container. Docker assigns a devcontainer a new random name on every rebuild, so a pinned name breaks as soon as you rebuild. The devcontainer.local_folder label is stable, and the mirror follows the container across rebuilds.

What the image needs:

• herdr, running (herdr status inside the container should report a live server). This is the same requirement an ssh host has.
• socat, which bridges herdr's unix socket to docker exec's stdio. Docker has no equivalent of ssh's -L socket forward, so one small relay process per API connection does that job. Missing socat is a clear error, not a silent degrade.

A stopped container is not an error. It reports as dormant and is retried every 5 minutes rather than on the fast reconnect ladder, because "not running" is a container's resting state — unlike an unreachable ssh host.

Multiple containers each get their own [hosts.*] entry and run independently, exactly like multiple ssh hosts.

Limitations

• Version-locked to preview until the terminal session streams reach stable; keep both ends on the same build.
• Latency above raw ssh: keystroke echo is a rendered frame round-trip, so there's a small constant delay. For latency-critical work, plain ssh <host> is always one command away.
• Layout geometry is copied, not linked: pane content and typing are always live — only sizes are a snapshot. Remote pane adds/removes reconcile, but a split-ratio change at the remote doesn't resize an existing mirror.
• No git status on mirror rows — herdr derives the sidebar git branch and ahead/behind from the local workspace cwd, and there's no API to feed it a remote repo's state, so mirror workspaces show no git chip. The remote's real branch and status stay visible in the streamed pane's prompt.
• No custom sidebar UI (plugin API limitation): mirrors carry a <host>: label prefix and the daemon keeps them ordered into per-host groups, but it can't render a richer affordance (group headers, collapse, colour).
• Remote must be reachable and running herdr; the daemon surfaces a readable status if a host is down or on too old a version.

License

MIT — see LICENSE.