docs: changelog for v0.0.24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,4 @@
+.git
+testenv/.keys
+testenv/.state
+testenv/.artifacts

.gitignore

@@ -19,3 +19,8 @@ dist/
 # OS
 .DS_Store
 Thumbs.db
+
+# local test environment (testenv/up.sh)
+testenv/.keys/
+testenv/.state/
+testenv/.artifacts/

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.0.24
+
+- Fix the `interface_name` resolver strategy: it sent filter names that NetBox ignores and therefore returned the host's first IP address instead of the named interface's. It now uses NetBox's `interface` and `vminterface` filters; a missing interface falls through to the next strategy.
+- Fix `netssh sftp` and `netssh scp` with instance-qualified hosts (`prod/web01:/path`), which were taken for local paths.
+- Fix shell aliases of instance-qualified hosts ignoring anchored rewrite rules (`fsn_fsn1-pve1` instead of `fsn_fsnpve1`).
+- Add `netssh multi` to open several hosts side by side in tmux or zellij: host lists, `tag:`, NetBox virtualization clusters (`cluster:`, devices by default, `--kind vm|all`), and groups from the config (`@name`). `--sync` sends typing to all panes; `netssh sync` toggles it later. In the TUI, `Space` marks hosts and `Enter` opens them together. Configurable in `netssh configure` (multiplexer, panes per window, groups).
+- tmux keys for broadcast in `netssh multi` windows: prefix `S` toggles all panes, prefix `e` excludes the current pane (border `[SOLO]`) or includes it again; also `netssh sync --pane`. Both keys are unbound in a default tmux, are not bound if your tmux.conf uses them, act only in netssh windows, and can be changed or turned off (`multi.sync_key`, `multi.solo_key`).
+- `netssh multi` widens the status bar of its own tmux session, which tmux otherwise cuts to `[netssh-pv`.
+- Cache entries remember the NetBox cluster of a host, for `cluster:` completion and offline use.
+- Add `testenv/`, a local Docker environment with two NetBox instances, SSH targets, a jump host, tmux, zellij, and bash/zsh/fish, and 185 end-to-end checks of all features, including `netssh multi` with real tmux and zellij and screenshot checks of what a real terminal (xterm) renders (`testenv/up.sh`, `testenv/test.sh`). Not part of CI/CD.
+
 ## v0.0.23
 
 - `netssh configure` now covers every setting: after the instances, a menu opens with SSH defaults, SSH options (jump host, host key checking, connection target, address family, extra arguments, `-o` options), SSH rules (add, edit, remove by tag, instance, kind, name pattern), resolver & cache (including the cache file), shortcuts & command alias, and completion (`max_results`). SSH options can also be set per NetBox instance from the instance list.

README.md

@@ -21,7 +21,7 @@ The same lookup drives `netssh sftp`, `netssh scp`, and `netssh tunnel`, the int
 - [Installation](#installation)
 - [Quick start](#quick-start)
 - [Configuration](#configuration) — [wizard](#interactive-wizard), [manual config](#manual-config), [reference](#configuration-reference), [environment variables](#environment-variables), [files](#files-and-directories), [multiple instances](#multiple-netbox-instances)
-- [Usage](#usage) — [command overview](#command-overview), [SSH options](#ssh-options), [SFTP & SCP](#sftp-and-scp), [port forwarding](#port-forwarding), [static hosts](#static-hosts), [shortcuts](#host-shortcuts), [TUI](#interactive-tui), [notes](#server-notes), [cache](#cache-management)
+- [Usage](#usage) — [command overview](#command-overview), [SSH options](#ssh-options), [SFTP & SCP](#sftp-and-scp), [port forwarding](#port-forwarding), [static hosts](#static-hosts), [multiple servers](#multiple-servers-in-one-window), [shortcuts](#host-shortcuts), [TUI](#interactive-tui), [notes](#server-notes), [cache](#cache-management)
 - [Recipes](#recipes)
 - [IP Resolution Strategies](#ip-resolution-strategies)
 - [Shell Completion](#shell-completion) and [Shell Hook](#shell-hook)
@@ -50,6 +50,7 @@ The same lookup drives `netssh sftp`, `netssh scp`, and `netssh tunnel`, the int
 - **Automatic 24h cache refresh** — the cache is refreshed in the background every 24 hours
 - **Jump hosts and SSH options** — `proxy_jump`, host key checking, connection target, and free `-o` options per netssh, per NetBox instance, or per tag/name rule — without touching `~/.ssh/config`
 - **SFTP & SCP** — `netssh sftp host` and `netssh scp file host:/tmp/` with the same host lookup, shortcuts, and SSH options as ssh
+- **Several servers in one window** — `netssh multi` opens hosts, a tag, a NetBox cluster, or a saved group side by side in tmux or zellij, with optional typing into all of them
 - **Port forwarding** — named forwards in the config (`netssh tunnel host web`, `netssh --forward web host`), ad hoc specs, and `Ctrl+T` in the TUI
 - **Dry run** — `netssh --dry-run host` prints the final `ssh` command instead of connecting
 - **Clean uninstall** — `netssh uninstall` removes the binary, profile entries of all versions, completions, cache, and config
@@ -149,6 +150,7 @@ A menu then gives access to every other setting; open only the sections you want
 | SSH options | `proxy_jump`, `host_key_checking`, `target`, `address_family`, `extra_args` (one per line), `options` (`Key=Value` per line), `forwards` (`NAME L\|R\|D SPEC` per line) |
 | SSH rules | add, edit, remove `ssh.rules` — match by tag, instance, kind, name pattern, each with its own SSH options |
 | Static hosts | add, edit, remove hosts that are not in NetBox, each with user, port, tags, and SSH options |
+| Multi-session | multiplexer (auto, tmux, zellij), panes per window, tmux keys for broadcast and excluding a pane, groups (`NAME: sel1, sel2` per line) |
 | Resolver & cache | strategies, management subnets, interface name, hostname domain, cache TTL, cache file |
 | Shortcuts & command alias | domain suffixes, hyphen stripping, rewrite rules (`REGEX => REPLACEMENT` per line), `shell.alias` |
 | Completion | `completion.max_results` |
@@ -232,10 +234,14 @@ Every key, its default, and the section that explains it. Keys marked *layered*
 | `completion.max_results` | int | `0` | Hostnames offered per `<Tab>`; `0` = unlimited. |
 | `shell.alias` | string | — | Short command name for netssh, e.g. `j` — see [Short command alias](#short-command-alias). |
 | `hosts[]` | list | `[]` | Static hosts with `name`, `address`, `user`, `port`, `tags`, `ssh` — see [Static hosts](#static-hosts). |
+| `groups` | map of lists | `{}` | Named host lists for `netssh multi @NAME`; entries are hosts or selectors. |
+| `multi.multiplexer` | `auto` \| `tmux` \| `zellij` | `auto` | Which multiplexer `netssh multi` uses. |
+| `multi.panes_per_window` | int | `9` | More hosts open in further tmux windows or zellij tabs. |
+| `multi.sync_key`, `multi.solo_key` | tmux key \| `none` | `S`, `e` | Keys after the tmux prefix: broadcast to all panes, exclude/include the current pane. |
 
 ### Environment variables
 
-These variables override the file. Lists are comma-separated (`NETSSH_SHORTCUTS_DOMAINS=.example.com,.example.de`). Settings without a variable (`extra_args`, `options`, `forwards`, `rules`, `rewrites`, `netboxes`, `hosts`) can only be set in the file.
+These variables override the file. Lists are comma-separated (`NETSSH_SHORTCUTS_DOMAINS=.example.com,.example.de`). Settings without a variable (`extra_args`, `options`, `forwards`, `rules`, `rewrites`, `netboxes`, `hosts`, `groups`) can only be set in the file.
 
 | Variable | Key |
 |---|---|
@@ -246,6 +252,7 @@ These variables override the file. Lists are comma-separated (`NETSSH_SHORTCUTS_
 | `NETSSH_SSH_PROXY_JUMP`, `NETSSH_SSH_HOST_KEY_CHECKING`, `NETSSH_SSH_TARGET`, `NETSSH_SSH_ADDRESS_FAMILY` | global `ssh.*` options |
 | `NETSSH_SHORTCUTS_DOMAINS`, `NETSSH_SHORTCUTS_STRIP_HYPHENS` | `shortcuts.*` |
 | `NETSSH_COMPLETION_MAX_RESULTS` | `completion.max_results` |
+| `NETSSH_MULTI_MULTIPLEXER`, `NETSSH_MULTI_PANES_PER_WINDOW` | `multi.*` |
 | `NETSSH_SHELL_ALIAS` | `shell.alias` |
 
 netssh also respects `XDG_CONFIG_HOME`, `XDG_CACHE_HOME`, `ZDOTDIR`, and `SHELL` (for `hook install`, `completion install`, and `alias` without `--shell`).
@@ -359,6 +366,8 @@ A hint is shown during `netssh configure` if a legacy v1 token is entered.
 | `netssh scp [netssh flags] [scp options] SOURCE... TARGET` | Copy files — see [SFTP and SCP](#sftp-and-scp). |
 | `netssh tunnel [netssh flags] [ssh options] HOST FORWARD...` | Port forwards without a shell — see [Port forwarding](#port-forwarding). |
 | `netssh hosts [list] \| add NAME ADDRESS [--user U] [--port P] [--tag T]... [--replace] \| remove NAME` | Manage static hosts — see [Static hosts](#static-hosts). |
+| `netssh multi [--sync] [--kind K] [--tmux\|--zellij] [-l U] [--jump H\|--no-jump] HOST\|tag:T\|cluster:C\|@GROUP...` | Several hosts side by side — see [Multiple servers](#multiple-servers-in-one-window). |
+| `netssh sync [--pane]` | Toggle typing into all panes of the current tmux window or zellij tab; `--pane` excludes/includes the current tmux pane. |
 | `netssh configure` | Setup wizard. |
 | `netssh cache list \| refresh [--tag T] [--kind device\|vm] [--instance I] \| clear` | Inspect and manage the host cache. |
 | `netssh search QUERY` | Print matching cached hostnames, one per line. |
@@ -513,7 +522,7 @@ netssh --forward web fsnbx1               # shell plus forward (repeatable)
 
 A value that is no configured name but a port spec (`[bind:]port:host:hostport`) becomes a local forward. `netssh tunnel` adds `-o ExitOnForwardFailure=yes`, so a port already in use fails instead of leaving a silent session. Without forward names it lists the forwards configured for the host. Forward names are completed after the host (`netssh tunnel fsnbx1 <Tab>`) and after `--forward`. In the TUI, `Ctrl+T` on a host opens an input with its configured forwards.
 
-`sftp`, `scp`, `tunnel`, and `hosts` are subcommands; to connect to a host with one of these names, use `netssh -- sftp`.
+`sftp`, `scp`, `tunnel`, `hosts`, `multi`, and `sync` are subcommands; to connect to a host with one of these names, use `netssh -- sftp`.
 
 ### Static hosts
 
@@ -547,6 +556,53 @@ Static hosts behave like NetBox hosts everywhere: `netssh router`, `sftp`, `scp`
 - Static hosts never expire and are not touched by `cache refresh` or `cache clear`; removing one from the config removes it everywhere.
 - `--netbox` notes and NetBox comments are not available for static hosts; local notes work.
 
+### Multiple servers in one window
+
+`netssh multi` opens one pane per host in tmux or zellij — for example every node of a Proxmox or Kubernetes cluster — and can send your typing to all of them at once.
+
+```sh
+netssh multi web01 web02 db01              # hosts, shortcuts, instance/host, static hosts
+netssh multi tag:k8s-worker                # all hosts with a NetBox tag (and static hosts with it)
+netssh multi cluster:pve-fsn1              # the devices (nodes) of a NetBox virtualization cluster
+netssh multi --kind vm cluster:pve-fsn1    # the cluster's VMs; --kind all for both
+netssh multi @k8s                          # a saved group
+netssh multi --sync @k8s                   # start with typing sent to every pane
+netssh multi --dry-run cluster:pve-fsn1    # show the hosts and tmux/zellij commands
+```
+
+Each pane runs `netssh HOST`, so lookup, shortcuts, user and port, jump hosts, and rules work as for a single connection. `-l USER`, `--jump HOST`, and `--no-jump` apply to every pane. A pane whose connection fails stays open with the error until you press Enter.
+
+**Groups** collect hosts and selectors under a name (or use `netssh configure` → *Multi-session*):
+
+```yaml
+groups:
+  k8s: [k8s-master1, "tag:k8s-worker"]
+  pve: ["cluster:pve-fsn1"]
+  all-web: ["@k8s", "tag:web", legacy-box]
+multi:
+  multiplexer: auto        # auto | tmux | zellij
+  panes_per_window: 9      # more hosts open in further windows/tabs
+  sync_key: S              # tmux: prefix S = broadcast on/off (none = no key)
+  solo_key: e              # tmux: prefix e = exclude/include this pane
+```
+
+**tmux and zellij.** With `auto`, netssh uses the multiplexer you are in; otherwise tmux, then zellij, whichever is installed (`--tmux` / `--zellij` choose explicitly).
+
+| | tmux | zellij |
+|---|---|---|
+| Inside a session | new window in the current session | new tab in the current session |
+| Outside | new session `netssh-NAME`, attached | new session from a generated layout |
+| Layout | tiled; pane borders show the host | grid; pane titles show the host |
+| Broadcast to all panes | `--sync`; toggle with `Ctrl+b S` or `netssh sync` | `--sync` inside zellij; toggle with `Ctrl+t` then `s` or `netssh sync` |
+| Exclude one pane | `Ctrl+b e` (again: include) or `netssh sync --pane` | not possible — zellij syncs whole tabs |
+| Shown in the border | `[SYNC]` receives broadcast, `[SOLO]` excluded | `(SYNC)` in the tab name |
+
+**Keys in tmux.** `S` and `e` are free in a default tmux (`E` would be "spread panes evenly"). netssh binds them after your prefix when it opens panes, but only if your own `tmux.conf` does not already use them — then it keeps your binding and says so. They act only in windows opened by `netssh multi`; elsewhere they just show a message. Change or turn them off with `multi.sync_key` / `multi.solo_key` (`none`), e.g. `sync_key: C-s` for `prefix Ctrl+s`.
+
+**In the TUI**, mark hosts with `Space` (or all listed hosts with `Ctrl+A`) and press `Enter` to open them together.
+
+`tag:` and `cluster:` ask NetBox (all instances); if NetBox is unreachable, netssh uses the cached hosts and prints a warning. More than 24 hosts need `--yes`. The 24-hour background cache refresh runs once, not in every pane.
+
 ### Default username
 
 Set `ssh.default_user` in the config to avoid typing a username every time:
@@ -664,6 +720,8 @@ The TUI opens with your 10 most-recently-connected hosts. Start typing to search
 | `Tab` | autocomplete top result into the search field |
 | `↑` / `↓` | navigate results |
 | `Enter` | connect to selected host |
+| `Space` | mark/unmark the host; with marks, `Enter` opens them side by side (`netssh multi`) |
+| `Ctrl+A` | mark all listed hosts (again: unmark all) |
 | `Ctrl+O` | open an SFTP session to the selected host |
 | `Ctrl+T` | start a tunnel: enter forward names or specs (`web, 8080:localhost:80`) |
 | `Ctrl+E` | open inline editor to override user/port before connecting |
@@ -827,6 +885,14 @@ netssh cache refresh && netssh alias --test fsn1-bx1.hoster.de
 netssh fsnbx1                   # also works as shell alias: fsnbx1
 ```
 
+**Maintenance on all nodes of a cluster at once**
+
+```sh
+netssh multi --sync cluster:pve-fsn1     # every node in one window, typing goes to all
+# … run apt upgrade on all nodes; Ctrl+b e on a node that needs something
+# different excludes just that one, Ctrl+b S turns broadcast off for all
+```
+
 **Deploy a file and restart a service**
 
 ```sh
@@ -1024,7 +1090,11 @@ Both are non-blocking — the refresh runs as a background process and never del
 | Saving notes with `--netbox` fails with a permission error | The API token is read-only. Local notes work without write permission. |
 | `<Tab>` completes files instead of hosts | Run `netssh completion install` and open a new terminal; for zsh also `rm -f ~/.zcompdump*`. |
 | Aliases missing in a new shell | `netssh hook install`, then a new terminal. The cache must not be empty. |
-| A host is named `sftp`, `scp`, `tunnel`, `hosts`, or like another subcommand | Use `netssh -- sftp`. |
+| A host is named `sftp`, `scp`, `tunnel`, `hosts`, `multi`, `sync`, or like another subcommand | Use `netssh -- sftp`. |
+| `netssh multi needs tmux or zellij` | Install one of them (`apt install tmux`, `brew install tmux`). |
+| zellij shows empty boxes in its tab and status bar | Those are Powerline arrows; use a Nerd Font in your terminal, or add `simplified_ui true` to `~/.config/zellij/config.kdl`. |
+| `cluster:x matches no hosts` | Clusters select devices by default; VMs need `--kind vm` or `--kind all`. The name is matched case-insensitively. |
+| `netssh multi` panes use another config | Inside an existing tmux/zellij session, panes get your `HOME` and `XDG_*` paths, but not `NETSSH_*` variables (they would be visible to other users in the process list). Put such settings in the config file. |
 
 ## Uninstall
 
@@ -1055,6 +1125,14 @@ go test ./...        # includes offline installer/update tests
 go build ./...       # build all packages
 ```
 
+End-to-end tests run against real services in a local Docker environment — two NetBox instances, SSH targets on separate networks, a jump host, an IPv6 host, tmux, zellij, and bash/zsh/fish. See [testenv/README.md](testenv/README.md). It is not part of CI/CD.
+
+```sh
+testenv/up.sh        # build and start (first start ~6 min)
+testenv/test.sh      # 185 checks: connect, strategies, instances, shortcuts, rules, sftp/scp, tunnels, notes, shells, TUI, configurator, multi with tmux and zellij, and what xterm renders (screenshots + OCR)
+testenv/down.sh
+```
+
 The test suite covers the cache, NetBox client (via `httptest`), IP resolver chain, the argument parsers for ssh, sftp, and scp, SSH options and rules, port forwards, config loading, the setup wizard, shortcut normalization and rewrites, completion, the TUI keys, and shell hook install/uninstall. Wrapper tests run the real command (`sftp`, `scp`, `tunnel` with `--dry-run`) in a subprocess against a pre-filled cache, so no NetBox or ssh server is needed.
 
 Project layout:
@@ -1067,6 +1145,7 @@ Project layout:
 | `internal/resolver` | IP resolution strategies. |
 | `internal/cache` | Host cache. |
 | `internal/ssh` | Argument parsing and option injection for ssh, sftp, scp. |
+| `internal/multiplex` | tmux and zellij layouts for `netssh multi`. |
 | `internal/shortcuts` | Shortcut normalization. |
 | `internal/tui` | Interactive search. |
 | `internal/setup` | Setup wizard. |
@@ -1079,7 +1158,7 @@ This is a **vibe-coded** project: the entire codebase — architecture, implemen
 
 ## How it works
 
-1. `netssh` checks whether the first argument is a known subcommand (`configure`, `cache`, `sftp`, `scp`, `tunnel`, `notes`, …). If not, it enters SSH wrapper mode; without arguments it starts the TUI.
+1. `netssh` checks whether the first argument is a known subcommand (`configure`, `cache`, `sftp`, `scp`, `tunnel`, `multi`, `notes`, …). If not, it enters SSH wrapper mode; without arguments it starts the TUI.
 2. On first run, or when neither a NetBox nor static hosts are configured, the interactive setup wizard starts automatically.
 3. It removes its own long options (`--dry-run`, `--jump`, `--no-jump`, `--forward`) and parses the remaining arguments with the flag table of the program it will run (ssh, sftp, or scp differ, e.g. in `-l` and `-P`) to find the destination: `[user@]host` for ssh, `[user@]host[:path]` for sftp, and every `host:path` operand for scp.
 4. It resolves the host: first the static hosts from `hosts:` (by name or shortcut), then an exact cache lookup, a shortcut match against the cache (domains, rewrites, hyphen folding), and finally NetBox (`/api/dcim/devices/` and `/api/virtualization/virtual-machines/`, all instances in parallel) with the resolver chain. A fresh cache entry needs no network request; new results are cached.

cmd/netssh/main.go

@@ -46,6 +46,8 @@ var managedSubcommands = map[string]bool{
 	"scp":        true,
 	"tunnel":     true,
 	"hosts":      true,
+	"multi":      true,
+	"sync":       true,
 }
 
 func main() {
@@ -130,6 +132,7 @@ func findDestination(client internalssh.Client, args []string) (*destination, er
 // runClient resolves the NetBox host in args and execs ssh, sftp, or scp.
 func runClient(client internalssh.Client, flags internalssh.WrapperFlags, args []string) {
 	cfg := loadConfigOrSetup()
+	client = client.WithInstances(instanceNames(cfg))
 
 	dest, err := findDestination(client, args)
 	if err != nil {
@@ -175,6 +178,15 @@ func hostDefaults(cfg *config.Config, host resolvedHost) (string, int) {
 	return user, port
 }
 
+// instanceNames lists the named NetBox instances, which may prefix hostnames.
+func instanceNames(cfg *config.Config) []string {
+	names := make([]string, 0, len(cfg.NetBoxes))
+	for _, source := range cfg.NetBoxes {
+		names = append(names, source.Name)
+	}
+	return names
+}
+
 // prependArgs puts extra before args and shifts the destination indices.
 func prependArgs(extra, args []string, dests []int) []string {
 	for i := range dests {
@@ -281,7 +293,7 @@ func resolveTarget(cfg *config.Config, host string) resolvedHost {
 		fatalf("IP resolution for %q: %v", host, err)
 	}
 
-	entry := cache.Entry{Name: target.Target(), IP: ip, Kind: target.Kind, Tags: target.Tags}
+	entry := cache.Entry{Name: target.Target(), IP: ip, Kind: target.Kind, Tags: target.Tags, Cluster: target.Cluster}
 	c.Upsert(entry)
 	return used(entry)
 }
@@ -379,6 +391,12 @@ func runTUI() {
 	if host == nil {
 		return
 	}
+	if host.Action == tui.ActionMulti {
+		if err := runMulti(cfg, host.Targets, multiFlags{}); err != nil {
+			fatalf("%v", err)
+		}
+		return
+	}
 
 	// Revalidate stale or live TUI results through the configured resolver chain.
 	var tags []string
@@ -403,7 +421,7 @@ func runTUI() {
 		if err != nil {
 			fatalf("IP resolution: %v", err)
 		}
-		c.Upsert(cache.Entry{Name: target.Target(), IP: host.IP, Kind: target.Kind, Tags: target.Tags})
+		c.Upsert(cache.Entry{Name: target.Target(), IP: host.IP, Kind: target.Kind, Tags: target.Tags, Cluster: target.Cluster})
 		tags = target.Tags
 	}
 	fmt.Fprintf(os.Stderr, "Connecting to %s (%s)…\n", host.Name, host.IP)
@@ -489,7 +507,7 @@ func rootCmd() *cobra.Command {
 		},
 	}
 
-	root.AddCommand(notesCmd(), configureCmd(), searchCmd(), cacheCmd(), aliasCmd(), hookCmd(), shellInitCmd(), versionCmd(), uninstallCmd(), sftpCmd(), scpCmd(), tunnelCmd(), hostsCmd())
+	root.AddCommand(notesCmd(), configureCmd(), searchCmd(), cacheCmd(), aliasCmd(), hookCmd(), shellInitCmd(), versionCmd(), uninstallCmd(), sftpCmd(), scpCmd(), tunnelCmd(), hostsCmd(), multiCmd(), syncCmd())
 
 	// cobra builds the "completion" command lazily; force init so we can extend it.
 	root.InitDefaultCompletionCmd()
@@ -744,7 +762,7 @@ func cacheRefreshCmd() *cobra.Command {
 					fmt.Fprintf(os.Stderr, "warning: skipping %s: %v\n", e.Name, err)
 					continue
 				}
-				c.Upsert(cache.Entry{Name: e.Target(), IP: ip, Kind: e.Kind, Tags: e.Tags})
+				c.Upsert(cache.Entry{Name: e.Target(), IP: ip, Kind: e.Kind, Tags: e.Tags, Cluster: e.Cluster})
 				written++
 			}
 
@@ -985,7 +1003,8 @@ func hookUninstallCmd() *cobra.Command {
 // maybeBackgroundRefresh starts a background `netssh cache refresh` if the cache
 // has not been fully refreshed within the last 24 hours.
 func maybeBackgroundRefresh(cfg *config.Config, c *cache.Cache) {
-	if !cfg.HasNetBox() {
+	// netssh multi checks once and starts its panes with NETSSH_NO_REFRESH.
+	if !cfg.HasNetBox() || os.Getenv("NETSSH_NO_REFRESH") != "" {
 		return
 	}
 	if !c.NeedsRefresh(24 * time.Hour) {

cmd/netssh/multi.go

@@ -0,0 +1,414 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/cache"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/multiplex"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/netbox"
+)
+
+// maxHostsWithoutConfirm guards against opening hundreds of panes by accident.
+const maxHostsWithoutConfirm = 24
+
+// multiFlags are the options shared by netssh multi and the TUI.
+type multiFlags struct {
+	kind, user, jump, multiplexer string
+	noJump, sync, dryRun, yes     bool
+}
+
+func multiCmd() *cobra.Command {
+	var f multiFlags
+	var useTmux, useZellij bool
+	cmd := &cobra.Command{
+		Use:   "multi [flags] HOST|tag:TAG|cluster:NAME|@GROUP...",
+		Short: "Open several hosts side by side in tmux or zellij",
+		Long: `Open one pane per host in a tmux window or zellij tab. Hosts are given as
+names (shortcuts, instance/host, static hosts) or selectors:
+
+  tag:TAG        all hosts with this NetBox tag, and static hosts with this tag
+  cluster:NAME   devices of a NetBox virtualization cluster (--kind vm|all for VMs)
+  @GROUP         a group from the config (groups:)
+
+Broadcast typing to all panes of a window with --sync, or toggle it later with
+netssh sync. Inside tmux or zellij the panes open in the current session.`,
+		Example: `  netssh multi web01 web02 db01
+  netssh multi cluster:pve-fsn1
+  netssh multi --kind vm cluster:pve-fsn1
+  netssh multi --sync tag:k8s-worker
+  netssh multi @k8s`,
+		Args: cobra.MinimumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if useTmux && useZellij {
+				return errors.New("--tmux and --zellij are mutually exclusive")
+			}
+			if useTmux {
+				f.multiplexer = multiplex.Tmux
+			} else if useZellij {
+				f.multiplexer = multiplex.Zellij
+			}
+			return runMulti(loadConfigOrSetup(), args, f)
+		},
+		ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]cobra.Completion, cobra.ShellCompDirective) {
+			cfg, err := config.Load()
+			if err != nil {
+				return nil, cobra.ShellCompDirectiveError
+			}
+			return multiCompletions(cfg, toComplete)
+		},
+	}
+	cmd.Flags().StringVar(&f.kind, "kind", "", "Host kind for tag: and cluster: — device, vm, or all (default: all for tags, device for clusters)")
+	cmd.Flags().BoolVar(&f.sync, "sync", false, "Start with typing broadcast to all panes")
+	cmd.Flags().BoolVar(&useTmux, "tmux", false, "Use tmux")
+	cmd.Flags().BoolVar(&useZellij, "zellij", false, "Use zellij")
+	cmd.Flags().StringVarP(&f.user, "user", "l", "", "Login user for every host")
+	cmd.Flags().StringVar(&f.jump, "jump", "", "Jump host for every host")
+	cmd.Flags().BoolVar(&f.noJump, "no-jump", false, "Disable jump hosts")
+	cmd.Flags().BoolVar(&f.dryRun, "dry-run", false, "Print the hosts and multiplexer commands")
+	cmd.Flags().BoolVarP(&f.yes, "yes", "y", false, fmt.Sprintf("Open more than %d hosts without asking", maxHostsWithoutConfirm))
+	_ = cmd.RegisterFlagCompletionFunc("kind", cobra.FixedCompletions([]cobra.Completion{"device", "vm", "all"}, cobra.ShellCompDirectiveNoFileComp))
+	return cmd
+}
+
+func syncCmd() *cobra.Command {
+	var pane bool
+	cmd := &cobra.Command{
+		Use:   "sync [--pane]",
+		Short: "Toggle typing into all panes of the current tmux window or zellij tab",
+		Long: `Toggle broadcast in the current tmux window or zellij tab. With --pane,
+exclude the current tmux pane from broadcast, or include it again.
+
+In windows opened by netssh multi, tmux also has keys for this:
+prefix S (all panes) and prefix e (this pane); see multi.sync_key and
+multi.solo_key. In zellij, use Ctrl+t then s.`,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			state, err := multiplex.ToggleSync(multiplex.System{}, pane)
+			if err != nil {
+				return err
+			}
+			fmt.Fprintln(os.Stderr, "netssh: "+state)
+			return nil
+		},
+	}
+	cmd.Flags().BoolVar(&pane, "pane", false, "Exclude the current tmux pane from broadcast, or include it again")
+	return cmd
+}
+
+// runMulti expands selectors and opens one pane per host.
+func runMulti(cfg *config.Config, selectors []string, f multiFlags) error {
+	if f.jump != "" && f.noJump {
+		return errors.New("--jump and --no-jump are mutually exclusive")
+	}
+	switch f.kind {
+	case "", "device", "vm", "all":
+	default:
+		return fmt.Errorf("--kind must be device, vm, or all")
+	}
+	c := newCache(cfg)
+	_ = c.Load()
+	targets, warnings, err := expandSelectors(cfg, c, selectors, f.kind)
+	for _, warning := range warnings {
+		fmt.Fprintln(os.Stderr, "netssh: warning: "+warning)
+	}
+	if err != nil {
+		return err
+	}
+	if len(targets) > maxHostsWithoutConfirm && !f.yes && !f.dryRun {
+		return fmt.Errorf("%d hosts selected; pass --yes to open them all", len(targets))
+	}
+
+	var runner multiplex.Runner = multiplex.System{}
+	if f.dryRun {
+		fmt.Printf("# %d hosts: %s\n", len(targets), strings.Join(targets, " "))
+		runner = &multiplex.DryRun{W: os.Stdout}
+	}
+	requested := f.multiplexer
+	if requested == "" {
+		requested = cfg.Multi.Multiplexer
+	}
+	kind, err := multiplex.Detect(requested, runner)
+	if err != nil {
+		return err
+	}
+	if !f.dryRun {
+		// Checked once here; the panes skip it (NETSSH_NO_REFRESH).
+		maybeBackgroundRefresh(cfg, c)
+	}
+
+	panes := make([]multiplex.Pane, 0, len(targets))
+	for _, target := range targets {
+		panes = append(panes, multiplex.Pane{Title: target, Argv: paneArgv(target, f)})
+	}
+	layoutDir := filepath.Dir(cfg.Cache.Path)
+	if err := os.MkdirAll(layoutDir, 0o700); err != nil {
+		return err
+	}
+	syncKey, soloKey := cfg.Multi.Keys()
+	return multiplex.Open(kind, panes, multiplex.Options{
+		SyncKey:   syncKey,
+		SoloKey:   soloKey,
+		Label:     multiLabel(selectors),
+		Sync:      f.sync,
+		PerWindow: cfg.Multi.PanesPerWindowOrDefault(),
+		LayoutDir: layoutDir,
+		Hint:      func(s string) { fmt.Fprintln(os.Stderr, "netssh: "+s) },
+	}, runner)
+}
+
+// paneArgv runs netssh for one host. Panes of an existing tmux or zellij
+// session inherit that server's environment, so the paths that select the
+// config and cache are passed explicitly; NETSSH_* values are not, because
+// arguments are visible to other users (tokens).
+func paneArgv(target string, f multiFlags) []string {
+	self, err := os.Executable()
+	if err != nil {
+		self = "netssh"
+	}
+	env, err := exec.LookPath("env")
+	if err != nil {
+		env = "/usr/bin/env"
+	}
+	argv := []string{env, "NETSSH_NO_REFRESH=1"}
+	for _, key := range []string{"HOME", "XDG_CONFIG_HOME", "XDG_CACHE_HOME"} {
+		if value, ok := os.LookupEnv(key); ok {
+			argv = append(argv, key+"="+value)
+		}
+	}
+	argv = append(argv, self)
+	switch {
+	case f.jump != "":
+		argv = append(argv, "--jump", f.jump)
+	case f.noJump:
+		argv = append(argv, "--no-jump")
+	}
+	if f.user != "" {
+		argv = append(argv, "-l", f.user)
+	}
+	return append(argv, target)
+}
+
+var unsafeLabel = regexp.MustCompile(`[^A-Za-z0-9_-]+`)
+
+// multiLabel names the window, session, or tab after a single selector.
+func multiLabel(selectors []string) string {
+	if len(selectors) != 1 {
+		return "multi"
+	}
+	s := selectors[0]
+	for _, prefix := range []string{"@", "tag:", "cluster:"} {
+		s = strings.TrimPrefix(s, prefix)
+	}
+	if s = strings.Trim(unsafeLabel.ReplaceAllString(s, "-"), "-"); s == "" {
+		return "multi"
+	}
+	return s
+}
+
+// expander resolves selectors into an ordered list of unique host targets.
+type expander struct {
+	cfg      *config.Config
+	cache    *cache.Cache
+	kind     string
+	client   *netbox.Client
+	seen     map[string]bool
+	visiting map[string]bool
+	targets  []string
+	warnings []string
+}
+
+func expandSelectors(cfg *config.Config, c *cache.Cache, selectors []string, kind string) ([]string, []string, error) {
+	e := &expander{cfg: cfg, cache: c, kind: kind, seen: map[string]bool{}, visiting: map[string]bool{}}
+	for _, selector := range selectors {
+		if err := e.expand(selector); err != nil {
+			return nil, e.warnings, err
+		}
+	}
+	if len(e.targets) == 0 {
+		return nil, e.warnings, errors.New("no hosts selected")
+	}
+	return e.targets, e.warnings, nil
+}
+
+func (e *expander) add(target string) {
+	key := strings.ToLower(target)
+	if !e.seen[key] {
+		e.seen[key] = true
+		e.targets = append(e.targets, target)
+	}
+}
+
+func (e *expander) expand(selector string) error {
+	switch {
+	case strings.HasPrefix(selector, "@"):
+		return e.group(strings.ToLower(strings.TrimPrefix(selector, "@")))
+	case strings.HasPrefix(selector, "tag:"):
+		return e.query(selector, netbox.SearchOptions{Tag: strings.TrimPrefix(selector, "tag:")}, "all")
+	case strings.HasPrefix(selector, "cluster:"):
+		return e.query(selector, netbox.SearchOptions{Cluster: strings.TrimPrefix(selector, "cluster:")}, "device")
+	case selector == "":
+		return nil
+	}
+	e.add(selector)
+	return nil
+}
+
+func (e *expander) group(name string) error {
+	members, ok := e.cfg.Groups[name]
+	if !ok {
+		names := make([]string, 0, len(e.cfg.Groups))
+		for group := range e.cfg.Groups {
+			names = append(names, "@"+group)
+		}
+		sort.Strings(names)
+		if len(names) == 0 {
+			return fmt.Errorf("unknown group @%s; no groups are configured (groups:)", name)
+		}
+		return fmt.Errorf("unknown group @%s; available: %s", name, strings.Join(names, ", "))
+	}
+	if e.visiting[name] {
+		return fmt.Errorf("group @%s contains itself", name)
+	}
+	e.visiting[name] = true
+	defer delete(e.visiting, name)
+	for _, member := range members {
+		if err := e.expand(member); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// query expands tag: and cluster: through NetBox, plus static hosts for tags;
+// if NetBox fails, the cache answers with a warning.
+func (e *expander) query(selector string, opts netbox.SearchOptions, defaultKind string) error {
+	kind := e.kind
+	if kind == "" {
+		kind = defaultKind
+	}
+	if kind != "all" {
+		opts.Kind = kind
+	}
+	before := len(e.targets)
+	if opts.Tag != "" && (kind == "all" || kind == config.StaticKind) {
+		for _, host := range e.cfg.Hosts {
+			if hasTag(host.Tags, opts.Tag) {
+				e.add(host.Name)
+			}
+		}
+	}
+	if e.cfg.HasNetBox() {
+		if e.client == nil {
+			e.client = newNetBoxClient(e.cfg)
+		}
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		entries, err := e.client.SearchAll(ctx, "", opts)
+		cancel()
+		if err != nil {
+			e.warnings = append(e.warnings, fmt.Sprintf("%s: NetBox unavailable, using the cache: %v", selector, err))
+			entries = e.fromCache(opts)
+		} else {
+			sort.Slice(entries, func(i, j int) bool { return entries[i].Target() < entries[j].Target() })
+		}
+		for _, entry := range entries {
+			e.add(entry.Target())
+		}
+	}
+	if len(e.targets) == before {
+		hint := ""
+		if opts.Cluster != "" && e.kind == "" {
+			hint = " (only devices by default; try --kind vm or --kind all)"
+		}
+		return fmt.Errorf("%s matches no hosts%s", selector, hint)
+	}
+	return nil
+}
+
+func (e *expander) fromCache(opts netbox.SearchOptions) []netbox.HostEntry {
+	var out []netbox.HostEntry
+	for _, entry := range e.cache.All() {
+		if entry.Static || opts.Kind != "" && entry.Kind != opts.Kind {
+			continue
+		}
+		if opts.Tag != "" && !hasTag(entry.Tags, opts.Tag) || opts.Cluster != "" && !strings.EqualFold(entry.Cluster, opts.Cluster) {
+			continue
+		}
+		source, name := netbox.SplitTarget(entry.Name)
+		out = append(out, netbox.HostEntry{Source: source, Name: name, Kind: entry.Kind})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Target() < out[j].Target() })
+	return out
+}
+
+// hasTag compares a tag by name or slug, like ssh.rules.
+func hasTag(tags []string, want string) bool {
+	for _, tag := range tags {
+		if strings.EqualFold(tag, want) || strings.EqualFold(strings.Join(strings.Fields(strings.ToLower(tag)), "-"), want) {
+			return true
+		}
+	}
+	return false
+}
+
+// multiCompletions offers hosts, @groups, and tag:/cluster: values from the cache.
+func multiCompletions(cfg *config.Config, toComplete string) ([]cobra.Completion, cobra.ShellCompDirective) {
+	c := newCache(cfg)
+	_ = c.Load()
+	lower := strings.ToLower(toComplete)
+	var out []string
+	switch {
+	case strings.HasPrefix(lower, "tag:"), strings.HasPrefix(lower, "cluster:"):
+		prefix, value, _ := strings.Cut(lower, ":")
+		values := map[string]bool{}
+		for _, entry := range c.All() {
+			if prefix == "tag" {
+				for _, tag := range entry.Tags {
+					values[strings.ToLower(tag)] = true
+				}
+			} else if entry.Cluster != "" {
+				values[entry.Cluster] = true
+			}
+		}
+		for v := range values {
+			if strings.HasPrefix(strings.ToLower(v), value) {
+				out = append(out, prefix+":"+v)
+			}
+		}
+	case strings.HasPrefix(lower, "@"):
+		for group := range cfg.Groups {
+			if strings.HasPrefix("@"+group, lower) {
+				out = append(out, "@"+group)
+			}
+		}
+	default:
+		out = completeHosts(toComplete)
+		var prefixes []string
+		for _, p := range []string{"tag:", "cluster:"} {
+			if toComplete != "" && strings.HasPrefix(p, lower) {
+				prefixes = append(prefixes, p)
+			}
+		}
+		if len(out) == 0 && len(prefixes) > 0 {
+			return prefixes, cobra.ShellCompDirectiveNoSpace | cobra.ShellCompDirectiveNoFileComp
+		}
+		for group := range cfg.Groups {
+			if toComplete == "" {
+				out = append(out, "@"+group)
+			}
+		}
+	}
+	sort.Strings(out)
+	return out, cobra.ShellCompDirectiveNoFileComp
+}

cmd/netssh/multi_test.go

@@ -0,0 +1,92 @@
+package main
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/cache"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
+)
+
+func TestExpandSelectors(t *testing.T) {
+	cfg := &config.Config{
+		Hosts: []config.StaticHost{{Name: "box", Address: "10.0.0.1", Tags: []string{"Web Servers"}}},
+		Groups: map[string][]string{
+			"all":  {"@web", "db1", "box"},
+			"web":  {"web1", "tag:web-servers", "web1"},
+			"loop": {"@loop"},
+		},
+	}
+	c := cache.New(t.TempDir()+"/hosts.json", 60).WithStatic(cfg.Hosts)
+	got, _, err := expandSelectors(cfg, c, []string{"@all", "WEB1"}, "")
+	if err != nil || !reflect.DeepEqual(got, []string{"web1", "box", "db1"}) {
+		t.Fatalf("got %v %v", got, err)
+	}
+	if _, _, err := expandSelectors(cfg, c, []string{"@loop"}, ""); err == nil || !strings.Contains(err.Error(), "contains itself") {
+		t.Fatalf("cycle: %v", err)
+	}
+	if _, _, err := expandSelectors(cfg, c, []string{"@nope"}, ""); err == nil || !strings.Contains(err.Error(), "available: @all, @loop, @web") {
+		t.Fatalf("unknown group: %v", err)
+	}
+	if _, _, err := expandSelectors(cfg, c, []string{"tag:web-servers"}, "device"); err == nil {
+		t.Fatal("--kind device must exclude static hosts")
+	}
+}
+
+// Without a reachable NetBox, tag: and cluster: fall back to the cache.
+func TestExpandSelectorsCacheFallback(t *testing.T) {
+	cfg := &config.Config{NetBox: config.NetBoxConfig{URL: "http://127.0.0.1:1", Token: "t", TokenVersion: 1}}
+	c := cache.New(t.TempDir()+"/hosts.json", 60)
+	c.Upsert(cache.Entry{Name: "node2", Kind: "device", Cluster: "pve"})
+	c.Upsert(cache.Entry{Name: "node1", Kind: "device", Cluster: "pve", Tags: []string{"pve"}})
+	c.Upsert(cache.Entry{Name: "vm1", Kind: "vm", Cluster: "pve"})
+	got, warnings, err := expandSelectors(cfg, c, []string{"cluster:PVE"}, "")
+	if err != nil || !reflect.DeepEqual(got, []string{"node1", "node2"}) || len(warnings) != 1 {
+		t.Fatalf("devices: %v %v %v", got, warnings, err)
+	}
+	if got, _, _ := expandSelectors(cfg, c, []string{"cluster:pve"}, "all"); len(got) != 3 {
+		t.Fatalf("all: %v", got)
+	}
+	if _, _, err := expandSelectors(cfg, c, []string{"cluster:other"}, ""); err == nil || !strings.Contains(err.Error(), "--kind vm") {
+		t.Fatalf("empty cluster: %v", err)
+	}
+}
+
+func TestMultiLabelAndPaneArgv(t *testing.T) {
+	for selectors, want := range map[string]string{"@k8s": "k8s", "cluster:pve-fsn1": "pve-fsn1", "tag:a.b": "a-b", "a b": "multi"} {
+		if got := multiLabel(strings.Fields(selectors)); got != want {
+			t.Errorf("%q: got %q", selectors, got)
+		}
+	}
+	t.Setenv("XDG_CONFIG_HOME", "/cfg")
+	t.Setenv("NETSSH_NETBOX_TOKEN", "secret")
+	argv := strings.Join(paneArgv("prod/web1", multiFlags{user: "ops", jump: "jh"}), " ")
+	for _, want := range []string{"NETSSH_NO_REFRESH=1", "XDG_CONFIG_HOME=/cfg", "--jump jh -l ops prod/web1"} {
+		if !strings.Contains(argv, want) {
+			t.Errorf("argv lacks %q: %s", want, argv)
+		}
+	}
+	if strings.Contains(argv, "secret") {
+		t.Fatalf("token leaked into the pane arguments: %s", argv)
+	}
+}
+
+func TestMultiDryRun(t *testing.T) {
+	prepareConfig(t, "hosts:\n  - {name: a, address: 10.0.0.1, tags: [web]}\n  - {name: b, address: 10.0.0.2, tags: [web]}\ngroups:\n  web: [\"tag:web\"]\n")
+	out, err := runNetssh(t, "multi", "--dry-run", "--tmux", "--sync", "@web")
+	if err != nil {
+		t.Fatalf("%s %v", out, err)
+	}
+	for _, want := range []string{"# 2 hosts: a b", "tmux new-session -d -x 240 -y 70 -s netssh-web", "synchronize-panes on", "tmux attach-session -t netssh-web"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("missing %q:\n%s", want, out)
+		}
+	}
+	if out, err := runNetssh(t, "multi", "--dry-run", "--zellij", "a", "b"); err != nil || !strings.Contains(out, `pane name="b"`) {
+		t.Errorf("zellij: %s %v", out, err)
+	}
+	if out, err := runNetssh(t, "sync"); err == nil || !strings.Contains(out, "inside tmux or zellij") {
+		t.Errorf("sync outside: %s %v", out, err)
+	}
+}

internal/cache/cache.go

@@ -21,6 +21,7 @@ type Entry struct {
 	IP       string    `json:"ip"`
 	Kind     string    `json:"kind"`
 	Tags     []string  `json:"tags,omitempty"`
+	Cluster  string    `json:"cluster,omitempty"`
 	CachedAt time.Time `json:"cached_at"`
 	LastUsed time.Time `json:"last_used,omitempty"`
 	// Static marks a host from the config's hosts: list. It never expires;

internal/config/config.go

@@ -20,6 +20,9 @@ type Config struct {
 	Shortcuts  ShortcutsConfig  `mapstructure:"shortcuts"`
 	Completion CompletionConfig `mapstructure:"completion"`
 	Hosts      []StaticHost     `mapstructure:"hosts"`
+	// Groups name lists of hosts and selectors for netssh multi (@name).
+	Groups map[string][]string `mapstructure:"groups"`
+	Multi  MultiConfig         `mapstructure:"multi"`
 }
 
 type ShellConfig struct {
@@ -117,7 +120,7 @@ func Load() (*Config, error) {
 	v.SetEnvPrefix("NETSSH")
 	v.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
 	v.AutomaticEnv()
-	for _, key := range []string{"netbox.url", "netbox.token", "netbox.token_version", "resolver.strategies", "resolver.management_subnets", "resolver.interface_name", "resolver.hostname_domain", "cache.ttl", "cache.path", "ssh.default_user", "ssh.default_port", "shortcuts.domains", "shortcuts.strip_hyphens", "shell.alias", "ssh.proxy_jump", "ssh.host_key_checking", "ssh.target", "ssh.address_family", "completion.max_results"} {
+	for _, key := range []string{"netbox.url", "netbox.token", "netbox.token_version", "resolver.strategies", "resolver.management_subnets", "resolver.interface_name", "resolver.hostname_domain", "cache.ttl", "cache.path", "ssh.default_user", "ssh.default_port", "shortcuts.domains", "shortcuts.strip_hyphens", "shell.alias", "ssh.proxy_jump", "ssh.host_key_checking", "ssh.target", "ssh.address_family", "completion.max_results", "multi.multiplexer", "multi.panes_per_window"} {
 		if err := v.BindEnv(key); err != nil {
 			return nil, err
 		}
@@ -163,6 +166,9 @@ func Load() (*Config, error) {
 	if err := cfg.ValidateHosts(); err != nil {
 		return nil, err
 	}
+	if err := cfg.ValidateMulti(); err != nil {
+		return nil, err
+	}
 	for i := range cfg.NetBoxes {
 		source := &cfg.NetBoxes[i]
 		source.Name = strings.ToLower(source.Name)

internal/config/multi.go

@@ -0,0 +1,92 @@
+package config
+
+import (
+	"fmt"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// MultiConfig controls netssh multi.
+type MultiConfig struct {
+	// Multiplexer is auto, tmux, or zellij; empty means auto.
+	Multiplexer string `mapstructure:"multiplexer"`
+	// PanesPerWindow splits larger host lists into more windows or tabs; 0 = 9.
+	PanesPerWindow int `mapstructure:"panes_per_window"`
+	// SyncKey and SoloKey are tmux prefix keys for broadcast to all panes and
+	// for excluding the current pane; empty = default (S, e), "none" = off.
+	SyncKey string `mapstructure:"sync_key"`
+	SoloKey string `mapstructure:"solo_key"`
+}
+
+// Default tmux keys: unbound in a stock tmux (E would be "spread evenly").
+const (
+	DefaultSyncKey = "S"
+	DefaultSoloKey = "e"
+)
+
+// Keys returns the tmux keys to bind; "" for a disabled one.
+func (m MultiConfig) Keys() (sync, solo string) {
+	pick := func(key, fallback string) string {
+		switch key {
+		case "":
+			return fallback
+		case "none":
+			return ""
+		}
+		return key
+	}
+	return pick(m.SyncKey, DefaultSyncKey), pick(m.SoloKey, DefaultSoloKey)
+}
+
+var tmuxKey = regexp.MustCompile(`^([CMS]-)*([A-Za-z0-9]|F[0-9]{1,2}|[-_=+!@#$%^&*,./?<>\[\]]|Tab|Space|Enter|BSpace|Up|Down|Left|Right|Home|End|PPage|NPage)$`)
+
+// DefaultPanesPerWindow keeps panes readable on a normal screen (3×3).
+const DefaultPanesPerWindow = 9
+
+// ValidateMulti checks groups and the multi settings.
+func (c *Config) ValidateMulti() error {
+	switch c.Multi.Multiplexer {
+	case "", "auto", "tmux", "zellij":
+	default:
+		return fmt.Errorf("multi.multiplexer must be auto, tmux, or zellij")
+	}
+	if c.Multi.PanesPerWindow < 0 || c.Multi.PanesPerWindow > 64 {
+		return fmt.Errorf("multi.panes_per_window must be between 1 and 64")
+	}
+	for name, key := range map[string]string{"sync_key": c.Multi.SyncKey, "solo_key": c.Multi.SoloKey} {
+		if key != "" && key != "none" && !tmuxKey.MatchString(key) {
+			return fmt.Errorf("multi.%s %q is not a tmux key (e.g. S, e, C-s, F5) or none", name, key)
+		}
+	}
+	if sync, solo := c.Multi.Keys(); sync != "" && sync == solo {
+		return fmt.Errorf("multi.sync_key and multi.solo_key must differ")
+	}
+	names := make([]string, 0, len(c.Groups))
+	for name := range c.Groups {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	for _, name := range names {
+		if !instanceName.MatchString(name) {
+			return fmt.Errorf("groups: name %q must contain only letters, digits, underscores, or hyphens", name)
+		}
+		if len(c.Groups[name]) == 0 {
+			return fmt.Errorf("groups.%s: needs at least one host or selector", name)
+		}
+		for _, selector := range c.Groups[name] {
+			if strings.TrimSpace(selector) == "" || strings.ContainsAny(selector, " \t\n") || strings.HasPrefix(selector, "-") {
+				return fmt.Errorf("groups.%s: invalid entry %q", name, selector)
+			}
+		}
+	}
+	return nil
+}
+
+// PanesPerWindowOrDefault returns the configured value or the default.
+func (m MultiConfig) PanesPerWindowOrDefault() int {
+	if m.PanesPerWindow > 0 {
+		return m.PanesPerWindow
+	}
+	return DefaultPanesPerWindow
+}

internal/config/ssh_test.go

@@ -190,3 +190,23 @@ func TestStaticHostsValidation(t *testing.T) {
 		}
 	}
 }
+
+func TestMultiConfig(t *testing.T) {
+	cfg, err := loadYAML(t, "groups:\n  K8s: [master1, \"tag:worker\"]\nmulti:\n  multiplexer: zellij\n")
+	if err != nil || len(cfg.Groups["k8s"]) != 2 || cfg.Multi.Multiplexer != "zellij" || cfg.Multi.PanesPerWindowOrDefault() != 9 {
+		t.Fatalf("%+v %v", cfg, err)
+	}
+	if sync, solo := cfg.Multi.Keys(); sync != "S" || solo != "e" {
+		t.Fatalf("default keys %q %q", sync, solo)
+	}
+	custom, err := loadYAML(t, "multi: {sync_key: C-s, solo_key: none}\n")
+	if sync, solo := custom.Multi.Keys(); err != nil || sync != "C-s" || solo != "" {
+		t.Fatalf("custom keys %q %q %v", sync, solo, err)
+	}
+	for _, bad := range []string{"multi: {multiplexer: screen}", "multi: {panes_per_window: 100}", "groups: {web: []}", "groups: {web: [\"a b\"]}",
+		"multi: {sync_key: \"x y\"}", "multi: {sync_key: \"{\"}", "multi: {sync_key: e}"} {
+		if _, err := loadYAML(t, bad+"\n"); err == nil {
+			t.Errorf("%s accepted", bad)
+		}
+	}
+}

internal/multiplex/multiplex.go

@@ -0,0 +1,251 @@
+// Package multiplex opens several commands side by side in tmux or zellij.
+package multiplex
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"strings"
+	"syscall"
+)
+
+// Pane is one command shown in its own pane.
+type Pane struct {
+	Title string
+	Argv  []string
+}
+
+// Options control how panes are laid out.
+type Options struct {
+	Label     string // window, session, and tab name
+	Sync      bool   // type into all panes of a window at once
+	PerWindow int    // panes per tmux window or zellij tab
+	LayoutDir string // where zellij layout files and tmux key bindings are written
+	// SyncKey and SoloKey are tmux prefix keys that toggle broadcast for the
+	// window and exclude the current pane from it; empty means no binding.
+	SyncKey, SoloKey string
+	// Hint receives notes for the user before the process is replaced.
+	Hint func(string)
+}
+
+// Runner executes multiplexer commands; tests and --dry-run replace it.
+type Runner interface {
+	// Output runs argv and returns its trimmed standard output.
+	Output(argv ...string) (string, error)
+	// Exec replaces the current process with argv.
+	Exec(argv ...string) error
+	LookPath(name string) (string, error)
+	Getenv(key string) string
+	WriteFile(path string, data []byte) error
+}
+
+// Supported multiplexers.
+const (
+	Tmux   = "tmux"
+	Zellij = "zellij"
+)
+
+// ErrNone means neither tmux nor zellij is available.
+var ErrNone = errors.New("netssh multi needs tmux or zellij; install one of them (e.g. apt install tmux)")
+
+// Detect picks the multiplexer: the requested one, else the one netssh runs
+// in, else tmux, else zellij.
+func Detect(requested string, r Runner) (string, error) {
+	switch requested {
+	case Tmux, Zellij:
+		if _, err := r.LookPath(requested); err != nil {
+			return "", fmt.Errorf("%s is not installed", requested)
+		}
+		return requested, nil
+	case "", "auto":
+	default:
+		return "", fmt.Errorf("unknown multiplexer %q", requested)
+	}
+	if r.Getenv("TMUX") != "" {
+		return Tmux, nil
+	}
+	if r.Getenv("ZELLIJ") != "" {
+		return Zellij, nil
+	}
+	for _, name := range []string{Tmux, Zellij} {
+		if _, err := r.LookPath(name); err == nil {
+			return name, nil
+		}
+	}
+	return "", ErrNone
+}
+
+// Open shows panes in the multiplexer. Outside of it, Open replaces the
+// process with the multiplexer client and only returns on error.
+func Open(kind string, panes []Pane, opts Options, r Runner) error {
+	if len(panes) == 0 {
+		return errors.New("no hosts to open")
+	}
+	if opts.Hint == nil {
+		opts.Hint = func(string) {}
+	}
+	if opts.PerWindow <= 0 {
+		opts.PerWindow = 9
+	}
+	if opts.Label == "" {
+		opts.Label = "netssh"
+	}
+	switch kind {
+	case Tmux:
+		return openTmux(panes, opts, r)
+	case Zellij:
+		return openZellij(panes, opts, r)
+	}
+	return fmt.Errorf("unknown multiplexer %q", kind)
+}
+
+// ToggleSync switches broadcast input in the current tmux window or zellij
+// tab; with pane it excludes the current tmux pane from it or includes it again.
+func ToggleSync(r Runner, pane bool) (string, error) {
+	if pane {
+		if r.Getenv("TMUX") == "" {
+			if r.Getenv("ZELLIJ") != "" {
+				return "", errors.New("zellij broadcasts to a whole tab; single panes cannot be excluded")
+			}
+			return "", errors.New("netssh sync --pane works inside tmux")
+		}
+		solo, err := r.Output("tmux", "display-message", "-p", "#{@netssh_solo}")
+		if err != nil {
+			return "", err
+		}
+		for _, argv := range soloToggle(solo == "1") {
+			if _, err := r.Output(argv...); err != nil {
+				return "", err
+			}
+		}
+		if solo == "1" {
+			return "pane included in broadcast", nil
+		}
+		return "pane excluded from broadcast", nil
+	}
+	switch {
+	case r.Getenv("TMUX") != "":
+		current, err := r.Output("tmux", "show-window-options", "-v", "synchronize-panes")
+		if err != nil {
+			return "", err
+		}
+		next := "on"
+		if current == "on" {
+			next = "off"
+		}
+		if _, err := r.Output("tmux", "set-window-option", "synchronize-panes", next); err != nil {
+			return "", err
+		}
+		return "broadcast " + next, nil
+	case r.Getenv("ZELLIJ") != "":
+		if _, err := r.Output("zellij", "action", "toggle-active-sync-tab"); err != nil {
+			return "", err
+		}
+		return "broadcast toggled", nil
+	}
+	return "", errors.New("netssh sync works inside tmux or zellij")
+}
+
+// chunks splits panes into groups of at most n.
+func chunks(panes []Pane, n int) [][]Pane {
+	var out [][]Pane
+	for len(panes) > n {
+		out = append(out, panes[:n])
+		panes = panes[n:]
+	}
+	return append(out, panes)
+}
+
+// windowLabel numbers windows when the panes need more than one.
+func windowLabel(label string, i, total int) string {
+	if total == 1 {
+		return label
+	}
+	return fmt.Sprintf("%s-%d", label, i+1)
+}
+
+// System runs real commands.
+type System struct{}
+
+func (System) Output(argv ...string) (string, error) {
+	cmd := exec.Command(argv[0], argv[1:]...)
+	var stderr strings.Builder
+	cmd.Stderr = &stderr
+	out, err := cmd.Output()
+	if err != nil {
+		if msg := strings.TrimSpace(stderr.String()); msg != "" {
+			return "", fmt.Errorf("%s: %s", argv[0], msg)
+		}
+		return "", fmt.Errorf("%s: %w", argv[0], err)
+	}
+	return strings.TrimSpace(string(out)), nil
+}
+
+func (System) Exec(argv ...string) error {
+	path, err := exec.LookPath(argv[0])
+	if err != nil {
+		return err
+	}
+	return syscall.Exec(path, argv, os.Environ())
+}
+
+func (System) LookPath(name string) (string, error) { return exec.LookPath(name) }
+func (System) Getenv(key string) string             { return os.Getenv(key) }
+func (System) WriteFile(path string, data []byte) error {
+	return os.WriteFile(path, data, 0o600)
+}
+
+// DryRun prints commands instead of running them; Output returns fake IDs.
+type DryRun struct {
+	W   io.Writer
+	Env map[string]string // values for Getenv, e.g. TMUX
+	n   int
+}
+
+func (d *DryRun) Output(argv ...string) (string, error) {
+	fmt.Fprintln(d.W, shellJoin(argv))
+	d.n++
+	switch {
+	case len(argv) > 1 && (argv[1] == "new-window" || argv[1] == "new-session"):
+		return fmt.Sprintf("@%d %%%d", d.n, d.n), nil
+	case len(argv) > 1 && argv[1] == "split-window":
+		return fmt.Sprintf("%%%d", d.n), nil
+	case len(argv) > 1 && argv[1] == "has-session":
+		return "", errors.New("no session")
+	}
+	return "", nil
+}
+
+func (d *DryRun) Exec(argv ...string) error {
+	fmt.Fprintln(d.W, shellJoin(argv))
+	return nil
+}
+
+// LookPath pretends every multiplexer is installed, so --dry-run shows the
+// commands on machines without tmux or zellij.
+func (d *DryRun) LookPath(name string) (string, error) { return name, nil }
+func (d *DryRun) Getenv(key string) string {
+	if v, ok := d.Env[key]; ok {
+		return v
+	}
+	return os.Getenv(key)
+}
+func (d *DryRun) WriteFile(path string, data []byte) error {
+	fmt.Fprintf(d.W, "# %s\n%s", path, data)
+	return nil
+}
+
+// shellJoin quotes argv for display.
+func shellJoin(argv []string) string {
+	quoted := make([]string, len(argv))
+	for i, arg := range argv {
+		if arg != "" && strings.Trim(arg, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789@%+=:,./_-") == "" {
+			quoted[i] = arg
+			continue
+		}
+		quoted[i] = "'" + strings.ReplaceAll(arg, "'", `'\''`) + "'"
+	}
+	return strings.Join(quoted, " ")
+}

internal/multiplex/multiplex_test.go

@@ -0,0 +1,281 @@
+package multiplex
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+)
+
+// fake records commands and answers like tmux and zellij would.
+type fake struct {
+	env       map[string]string
+	installed map[string]bool
+	sessions  map[string]bool
+	calls     []string
+	exec      []string
+	files     map[string]string
+	syncState string
+	keys      map[string]string // existing prefix bindings by key
+	solo      string
+	n         int
+}
+
+func newFake(env map[string]string, installed ...string) *fake {
+	f := &fake{env: env, installed: map[string]bool{}, sessions: map[string]bool{}, files: map[string]string{}, syncState: "off"}
+	for _, name := range installed {
+		f.installed[name] = true
+	}
+	return f
+}
+
+func (f *fake) Output(argv ...string) (string, error) {
+	f.calls = append(f.calls, strings.Join(argv, " "))
+	f.n++
+	switch argv[1] {
+	case "new-window", "new-session":
+		return fmt.Sprintf("@%d %%%d", f.n, f.n), nil
+	case "split-window":
+		return fmt.Sprintf("%%%d", f.n), nil
+	case "has-session":
+		if f.sessions[strings.TrimPrefix(argv[3], "=")] {
+			return "", nil
+		}
+		return "", errors.New("can't find session")
+	case "show-window-options":
+		return f.syncState, nil
+	case "list-keys":
+		return f.keys[argv[4]], nil
+	case "display-message":
+		return f.solo, nil
+	}
+	return "", nil
+}
+func (f *fake) Exec(argv ...string) error { f.exec = argv; return nil }
+func (f *fake) LookPath(name string) (string, error) {
+	if f.installed[name] {
+		return "/usr/bin/" + name, nil
+	}
+	return "", errors.New("not found")
+}
+func (f *fake) Getenv(key string) string { return f.env[key] }
+func (f *fake) WriteFile(path string, data []byte) error {
+	f.files[path] = string(data)
+	return nil
+}
+
+func panes(names ...string) []Pane {
+	out := make([]Pane, 0, len(names))
+	for _, name := range names {
+		out = append(out, Pane{Title: name, Argv: []string{"/usr/bin/netssh", name}})
+	}
+	return out
+}
+
+func TestDetect(t *testing.T) {
+	for _, tc := range []struct {
+		requested string
+		env       map[string]string
+		installed []string
+		want      string
+	}{
+		{"", map[string]string{"TMUX": "/tmp/tmux"}, []string{"tmux", "zellij"}, Tmux},
+		{"auto", map[string]string{"ZELLIJ": "0"}, []string{"tmux", "zellij"}, Zellij},
+		{"", nil, []string{"tmux", "zellij"}, Tmux},
+		{"", nil, []string{"zellij"}, Zellij},
+		{"zellij", map[string]string{"TMUX": "x"}, []string{"tmux", "zellij"}, Zellij},
+	} {
+		got, err := Detect(tc.requested, newFake(tc.env, tc.installed...))
+		if err != nil || got != tc.want {
+			t.Errorf("%+v: got %q %v", tc, got, err)
+		}
+	}
+	if _, err := Detect("", newFake(nil)); !errors.Is(err, ErrNone) {
+		t.Errorf("nothing installed: %v", err)
+	}
+	if _, err := Detect("tmux", newFake(nil, "zellij")); err == nil {
+		t.Error("missing requested multiplexer accepted")
+	}
+}
+
+func TestTmuxInside(t *testing.T) {
+	f := newFake(map[string]string{"TMUX": "/tmp/tmux-1/default"}, "tmux")
+	if err := Open(Tmux, panes("a", "b", "c"), Options{Label: "pve", Sync: true, SyncKey: "S", SoloKey: "e", LayoutDir: "/tmp/l"}, f); err != nil {
+		t.Fatal(err)
+	}
+	script := "sh -c " + paneScript + " netssh-pane /usr/bin/netssh "
+	want := []string{
+		"tmux new-window -P -F #{window_id} #{pane_id} -n pve " + script + "a",
+		"tmux split-window -t @1 -P -F #{pane_id} " + script + "b",
+		"tmux select-layout -t @1 tiled",
+		"tmux split-window -t @1 -P -F #{pane_id} " + script + "c",
+		"tmux select-layout -t @1 tiled",
+		"tmux set-option -p -t %1 @netssh_host a",
+		"tmux set-option -p -t %2 @netssh_host b",
+		"tmux set-option -p -t %4 @netssh_host c",
+		"tmux set-window-option -t @1 @netssh 1",
+		"tmux set-window-option -t @1 pane-border-status top",
+		"tmux set-window-option -t @1 pane-border-format  #{@netssh_host}#{?pane_synchronized, [SYNC],#{?@netssh_solo, [SOLO],}} ",
+		"tmux set-window-option -t @1 synchronize-panes on",
+		"tmux show-options -gv prefix",
+		"tmux list-keys -T prefix S",
+		"tmux list-keys -T prefix e",
+		"tmux source-file /tmp/l/netssh-multi.tmux.conf",
+		"tmux select-window -t @1",
+	}
+	if strings.Join(f.calls, "\n") != strings.Join(want, "\n") {
+		t.Fatalf("calls:\n%s\nwant:\n%s", strings.Join(f.calls, "\n"), strings.Join(want, "\n"))
+	}
+	if f.exec != nil {
+		t.Fatal("inside tmux must not attach")
+	}
+}
+
+func TestTmuxOutsideSplitsWindowsAndAvoidsSessionNames(t *testing.T) {
+	f := newFake(nil, "tmux")
+	f.sessions["netssh-pve"] = true
+	var hints []string
+	err := Open(Tmux, panes("a", "b", "c"), Options{Label: "pve", PerWindow: 2, Hint: func(s string) { hints = append(hints, s) }}, f)
+	if err != nil {
+		t.Fatal(err)
+	}
+	joined := strings.Join(f.calls, "\n")
+	for _, want := range []string{
+		"tmux has-session -t =netssh-pve-2",
+		"tmux new-session -d -x 240 -y 70 -s netssh-pve-2 -P -F #{window_id} #{pane_id} -n pve-1 ",
+		"tmux new-window -t netssh-pve-2: -P -F #{window_id} #{pane_id} -n pve-2 ",
+		"tmux set-option -t netssh-pve-2 status-left-length 40",
+	} {
+		if !strings.Contains(joined, want) {
+			t.Errorf("missing %q in\n%s", want, joined)
+		}
+	}
+	if strings.Contains(joined, "synchronize-panes") {
+		t.Error("sync set without --sync")
+	}
+	if strings.Join(f.exec, " ") != "tmux attach-session -t netssh-pve-2" || len(hints) != 1 {
+		t.Fatalf("exec %v hints %v", f.exec, hints)
+	}
+}
+
+func TestZellijOutsideWritesGridLayout(t *testing.T) {
+	f := newFake(nil, "zellij")
+	if err := Open(Zellij, panes("a", "b", "c", `q"x`), Options{Label: "pve", LayoutDir: "/tmp/l"}, f); err != nil {
+		t.Fatal(err)
+	}
+	layout := f.files["/tmp/l/netssh-multi.kdl"]
+	for _, want := range []string{
+		`plugin location="zellij:tab-bar"`,
+		`tab name="pve" focus=true {`,
+		`pane split_direction="vertical" {`,
+		`pane name="a" command="/usr/bin/netssh" {`,
+		`args "a"`,
+		`pane name="q\"x" command="/usr/bin/netssh" {`,
+	} {
+		if !strings.Contains(layout, want) {
+			t.Errorf("layout lacks %q:\n%s", want, layout)
+		}
+	}
+	// 4 panes → 2 columns × 2 rows.
+	if n := strings.Count(layout, `split_direction="vertical"`); n != 2 {
+		t.Errorf("%d rows, want 2:\n%s", n, layout)
+	}
+	if strings.Join(f.exec, " ") != "zellij --layout /tmp/l/netssh-multi.kdl" {
+		t.Fatalf("exec %v", f.exec)
+	}
+}
+
+func TestZellijInsideAddsTabs(t *testing.T) {
+	f := newFake(map[string]string{"ZELLIJ": "0"}, "zellij")
+	if err := Open(Zellij, panes("a", "b", "c"), Options{Label: "pve", PerWindow: 2, Sync: true, LayoutDir: "/tmp/l"}, f); err != nil {
+		t.Fatal(err)
+	}
+	want := []string{
+		"zellij action new-tab --layout /tmp/l/netssh-multi-1.kdl",
+		"zellij action toggle-active-sync-tab",
+		"zellij action new-tab --layout /tmp/l/netssh-multi-2.kdl",
+		"zellij action toggle-active-sync-tab",
+	}
+	if strings.Join(f.calls, "\n") != strings.Join(want, "\n") {
+		t.Fatalf("calls:\n%s", strings.Join(f.calls, "\n"))
+	}
+	if !strings.Contains(f.files["/tmp/l/netssh-multi-2.kdl"], `tab name="pve-2"`) {
+		t.Fatalf("second tab: %s", f.files["/tmp/l/netssh-multi-2.kdl"])
+	}
+}
+
+func TestToggleSync(t *testing.T) {
+	f := newFake(map[string]string{"TMUX": "x"})
+	if state, err := ToggleSync(f, false); err != nil || state != "broadcast on" || f.calls[1] != "tmux set-window-option synchronize-panes on" {
+		t.Fatalf("%q %v %v", state, err, f.calls)
+	}
+	f.syncState = "on"
+	if state, _ := ToggleSync(f, false); state != "broadcast off" {
+		t.Fatalf("%q", state)
+	}
+	z := newFake(map[string]string{"ZELLIJ": "0"})
+	if _, err := ToggleSync(z, false); err != nil || z.calls[0] != "zellij action toggle-active-sync-tab" {
+		t.Fatalf("%v %v", err, z.calls)
+	}
+	if _, err := ToggleSync(newFake(nil), false); err == nil {
+		t.Fatal("outside a multiplexer accepted")
+	}
+}
+
+func TestTmuxKeyBindings(t *testing.T) {
+	f := newFake(map[string]string{"TMUX": "x"}, "tmux")
+	var hint string
+	if err := Open(Tmux, panes("a"), Options{SyncKey: "S", SoloKey: "e", LayoutDir: "/tmp/l", Hint: func(s string) { hint = s }}, f); err != nil {
+		t.Fatal(err)
+	}
+	conf := f.files["/tmp/l/netssh-multi.tmux.conf"]
+	for _, want := range []string{"bind-key -T prefix S if-shell -F '#{@netssh}'", "bind-key -T prefix e if-shell", "set-option -p synchronize-panes off"} {
+		if !strings.Contains(conf, want) {
+			t.Errorf("conf lacks %q:\n%s", want, conf)
+		}
+	}
+	if hint != "keys: C-b S broadcast to all panes, C-b e exclude/include this pane" {
+		t.Errorf("hint %q", hint)
+	}
+
+	// A key bound in the user's tmux.conf is left alone; netssh's own is replaced.
+	f = newFake(map[string]string{"TMUX": "x"}, "tmux")
+	f.keys = map[string]string{"S": "bind-key -T prefix S kill-server", "e": "bind-key -T prefix e if-shell -F #{@netssh} …"}
+	if err := Open(Tmux, panes("a"), Options{SyncKey: "S", SoloKey: "e", LayoutDir: "/tmp/l", Hint: func(s string) { hint = s }}, f); err != nil {
+		t.Fatal(err)
+	}
+	conf = f.files["/tmp/l/netssh-multi.tmux.conf"]
+	if strings.Contains(conf, "prefix S ") || !strings.Contains(conf, "prefix e ") {
+		t.Errorf("user binding overwritten or own binding not refreshed:\n%s", conf)
+	}
+	if !strings.Contains(hint, "C-b S kept your own binding") {
+		t.Errorf("hint %q", hint)
+	}
+
+	// No keys configured: nothing is bound.
+	f = newFake(map[string]string{"TMUX": "x"}, "tmux")
+	if err := Open(Tmux, panes("a"), Options{LayoutDir: "/tmp/l"}, f); err != nil {
+		t.Fatal(err)
+	}
+	if len(f.files) != 0 || strings.Contains(strings.Join(f.calls, "\n"), "source-file") {
+		t.Errorf("bound keys although disabled: %v", f.calls)
+	}
+}
+
+func TestToggleSyncPane(t *testing.T) {
+	f := newFake(map[string]string{"TMUX": "x"})
+	if state, err := ToggleSync(f, true); err != nil || state != "pane excluded from broadcast" {
+		t.Fatalf("%q %v", state, err)
+	}
+	if got := strings.Join(f.calls[1:], "; "); got != "tmux set-option -p synchronize-panes off; tmux set-option -p @netssh_solo 1" {
+		t.Fatalf("exclude: %s", got)
+	}
+	f = newFake(map[string]string{"TMUX": "x"})
+	f.solo = "1"
+	if state, _ := ToggleSync(f, true); state != "pane included in broadcast" || f.calls[1] != "tmux set-option -pu synchronize-panes" {
+		t.Fatalf("include: %q %v", state, f.calls)
+	}
+	if _, err := ToggleSync(newFake(map[string]string{"ZELLIJ": "0"}), true); err == nil || !strings.Contains(err.Error(), "whole tab") {
+		t.Fatalf("zellij: %v", err)
+	}
+}

internal/multiplex/tmux.go

@@ -0,0 +1,194 @@
+package multiplex
+
+import (
+	"fmt"
+	"path/filepath"
+	"strconv"
+	"strings"
+)
+
+// paneScript runs the pane's command and keeps a failed one on screen, so an
+// unreachable host shows its error instead of the pane vanishing.
+const paneScript = `"$@"; status=$?; if [ "$status" -ne 0 ]; then echo; echo "netssh exited with status $status, press Enter to close"; read -r _; fi`
+
+// tmuxArgv runs the pane through sh with argv as arguments: no quoting, and
+// independent of the user's default-shell (which may be fish).
+func tmuxArgv(p Pane) []string {
+	return append([]string{"sh", "-c", paneScript, "netssh-pane"}, p.Argv...)
+}
+
+// openTmux adds a window per chunk of panes: to the current session inside
+// tmux, else to a new detached session that is attached at the end.
+func openTmux(panes []Pane, opts Options, r Runner) error {
+	inside := r.Getenv("TMUX") != ""
+	session := ""
+	if !inside {
+		session = freeSession(r, "netssh-"+opts.Label)
+	}
+	groups := chunks(panes, opts.PerWindow)
+	first := ""
+	for i, group := range groups {
+		name := windowLabel(opts.Label, i, len(groups))
+		format := []string{"-P", "-F", "#{window_id} #{pane_id}", "-n", name}
+		var create []string
+		switch {
+		case inside:
+			create = append([]string{"tmux", "new-window"}, format...)
+		case i == 0:
+			// A large virtual size leaves room for the splits; attaching resizes it.
+			create = append([]string{"tmux", "new-session", "-d", "-x", "240", "-y", "70", "-s", session}, format...)
+		default:
+			create = append([]string{"tmux", "new-window", "-t", session + ":"}, format...)
+		}
+		out, err := r.Output(append(create, tmuxArgv(group[0])...)...)
+		if err != nil {
+			return err
+		}
+		if !inside && i == 0 {
+			// tmux cuts the status bar's session name at 10 characters
+			// ("[netssh-pv"); widen it for this session only.
+			if _, err := r.Output("tmux", "set-option", "-t", session, "status-left-length", "40"); err != nil {
+				return err
+			}
+		}
+		window, pane, _ := strings.Cut(out, " ")
+		if first == "" {
+			first = window
+		}
+		paneIDs := []string{pane}
+		for _, p := range group[1:] {
+			id, err := r.Output(append([]string{"tmux", "split-window", "-t", window, "-P", "-F", "#{pane_id}"}, tmuxArgv(p)...)...)
+			if err != nil {
+				return err
+			}
+			paneIDs = append(paneIDs, id)
+			// Re-tile after every split so the next one still has room.
+			if _, err := r.Output("tmux", "select-layout", "-t", window, "tiled"); err != nil {
+				return err
+			}
+		}
+		for j, id := range paneIDs {
+			// A pane may already be gone (host unreachable and closed); not fatal.
+			_, _ = r.Output("tmux", "set-option", "-p", "-t", id, "@netssh_host", group[j].Title)
+		}
+		windowOptions := [][]string{
+			{"@netssh", "1"}, // the key bindings act only in these windows
+			{"pane-border-status", "top"},
+			{"pane-border-format", " #{@netssh_host}#{?pane_synchronized, [SYNC],#{?@netssh_solo, [SOLO],}} "},
+		}
+		if opts.Sync {
+			windowOptions = append(windowOptions, []string{"synchronize-panes", "on"})
+		}
+		for _, option := range windowOptions {
+			if _, err := r.Output("tmux", "set-window-option", "-t", window, option[0], option[1]); err != nil {
+				return err
+			}
+		}
+	}
+	keys, err := bindKeys(r, opts)
+	if err != nil {
+		return err
+	}
+	if keys != "" {
+		opts.Hint(keys)
+	}
+	if inside {
+		_, err := r.Output("tmux", "select-window", "-t", first)
+		return err
+	}
+	return r.Exec("tmux", "attach-session", "-t", session)
+}
+
+// soloToggle excludes the current pane from broadcast (a pane-level
+// synchronize-panes off) or includes it again by removing that override.
+func soloToggle(solo bool) [][]string {
+	if solo {
+		return [][]string{
+			{"tmux", "set-option", "-pu", "synchronize-panes"},
+			{"tmux", "set-option", "-pu", "@netssh_solo"},
+		}
+	}
+	return [][]string{
+		{"tmux", "set-option", "-p", "synchronize-panes", "off"},
+		{"tmux", "set-option", "-p", "@netssh_solo", "1"},
+	}
+}
+
+// keyBindings toggle broadcast in netssh multi windows; elsewhere they only
+// show a message, so they do not change what the keys mean to other windows.
+const syncBinding = `bind-key -T prefix %s if-shell -F '#{@netssh}' {
+  set-window-option synchronize-panes
+  display-message 'netssh: broadcast #{?synchronize-panes,on,off}'
+} {
+  display-message 'netssh: not a netssh multi window'
+}
+`
+
+const soloBinding = `bind-key -T prefix %s if-shell -F '#{@netssh}' {
+  if-shell -F '#{@netssh_solo}' {
+    set-option -pu synchronize-panes
+    set-option -pu @netssh_solo
+    display-message 'netssh: pane included in broadcast'
+  } {
+    set-option -p synchronize-panes off
+    set-option -p @netssh_solo 1
+    display-message 'netssh: pane excluded from broadcast'
+  }
+} {
+  display-message 'netssh: not a netssh multi window'
+}
+`
+
+// bindKeys installs the broadcast keys in the tmux server unless the user's
+// own configuration already uses them, and returns a hint naming the keys.
+func bindKeys(r Runner, opts Options) (string, error) {
+	prefix, err := r.Output("tmux", "show-options", "-gv", "prefix")
+	if err != nil || prefix == "" {
+		prefix = "C-b"
+	}
+	var conf strings.Builder
+	var hints, taken []string
+	for _, key := range []struct{ key, binding, what string }{
+		{opts.SyncKey, syncBinding, "broadcast to all panes"},
+		{opts.SoloKey, soloBinding, "exclude/include this pane"},
+	} {
+		if key.key == "" {
+			continue
+		}
+		// An existing binding is replaced only if netssh made it.
+		if existing, _ := r.Output("tmux", "list-keys", "-T", "prefix", key.key); existing != "" && !strings.Contains(existing, "@netssh") {
+			taken = append(taken, prefix+" "+key.key)
+			continue
+		}
+		fmt.Fprintf(&conf, key.binding, key.key)
+		hints = append(hints, prefix+" "+key.key+" "+key.what)
+	}
+	if conf.Len() > 0 {
+		path := filepath.Join(opts.LayoutDir, "netssh-multi.tmux.conf")
+		if err := r.WriteFile(path, []byte(conf.String())); err != nil {
+			return "", err
+		}
+		if _, err := r.Output("tmux", "source-file", path); err != nil {
+			return "", err
+		}
+	}
+	hint := "keys: " + strings.Join(hints, ", ")
+	if len(hints) == 0 {
+		hint = "toggle broadcast with: netssh sync, netssh sync --pane"
+	}
+	if len(taken) > 0 {
+		hint += "; " + strings.Join(taken, " and ") + " kept your own binding (use netssh sync)"
+	}
+	return hint, nil
+}
+
+// freeSession returns name, or name-2, name-3, … if a session already uses it.
+func freeSession(r Runner, name string) string {
+	candidate := name
+	for n := 2; ; n++ {
+		if _, err := r.Output("tmux", "has-session", "-t", "="+candidate); err != nil {
+			return candidate
+		}
+		candidate = name + "-" + strconv.Itoa(n)
+	}
+}

internal/multiplex/zellij.go

@@ -0,0 +1,101 @@
+package multiplex
+
+import (
+	"fmt"
+	"math"
+	"path/filepath"
+	"strings"
+)
+
+// openZellij writes a layout with one tab per chunk of panes. Inside zellij
+// each tab is added to the current session; outside, a new session starts.
+func openZellij(panes []Pane, opts Options, r Runner) error {
+	groups := chunks(panes, opts.PerWindow)
+	if r.Getenv("ZELLIJ") != "" {
+		for i, group := range groups {
+			path := filepath.Join(opts.LayoutDir, fmt.Sprintf("netssh-multi-%d.kdl", i+1))
+			tab := zellijTab(windowLabel(opts.Label, i, len(groups)), group, true)
+			if err := r.WriteFile(path, []byte(zellijLayout(tab))); err != nil {
+				return err
+			}
+			if _, err := r.Output("zellij", "action", "new-tab", "--layout", path); err != nil {
+				return err
+			}
+			if opts.Sync {
+				if _, err := r.Output("zellij", "action", "toggle-active-sync-tab"); err != nil {
+					return err
+				}
+			}
+		}
+		return nil
+	}
+	var tabs strings.Builder
+	for i, group := range groups {
+		tabs.WriteString(zellijTab(windowLabel(opts.Label, i, len(groups)), group, i == 0))
+	}
+	path := filepath.Join(opts.LayoutDir, "netssh-multi.kdl")
+	if err := r.WriteFile(path, []byte(zellijLayout(tabs.String()))); err != nil {
+		return err
+	}
+	if opts.Sync {
+		opts.Hint("zellij starts without broadcast: press Ctrl+t, then s, to type into all panes")
+	} else {
+		opts.Hint("toggle broadcast with Ctrl+t, then s (or netssh sync)")
+	}
+	return r.Exec("zellij", "--layout", path)
+}
+
+// zellijLayout wraps tabs with zellij's tab and status bars.
+func zellijLayout(tabs string) string {
+	return `layout {
+    default_tab_template {
+        pane size=1 borderless=true {
+            plugin location="zellij:tab-bar"
+        }
+        children
+        pane size=2 borderless=true {
+            plugin location="zellij:status-bar"
+        }
+    }
+` + tabs + "}\n"
+}
+
+// zellijTab arranges panes in a grid: rows of ceil(sqrt(n)) columns.
+func zellijTab(name string, panes []Pane, focus bool) string {
+	cols := int(math.Ceil(math.Sqrt(float64(len(panes)))))
+	var b strings.Builder
+	fmt.Fprintf(&b, "    tab name=%s", kdlString(name))
+	if focus {
+		b.WriteString(" focus=true")
+	}
+	b.WriteString(" {\n")
+	for start := 0; start < len(panes); start += cols {
+		row := panes[start:min(start+cols, len(panes))]
+		indent := "        "
+		if len(row) > 1 {
+			b.WriteString(indent + "pane split_direction=\"vertical\" {\n")
+			indent += "    "
+		}
+		for _, p := range row {
+			fmt.Fprintf(&b, "%spane name=%s command=%s {\n", indent, kdlString(p.Title), kdlString(p.Argv[0]))
+			if len(p.Argv) > 1 {
+				args := make([]string, 0, len(p.Argv)-1)
+				for _, arg := range p.Argv[1:] {
+					args = append(args, kdlString(arg))
+				}
+				fmt.Fprintf(&b, "%s    args %s\n", indent, strings.Join(args, " "))
+			}
+			b.WriteString(indent + "}\n")
+		}
+		if len(row) > 1 {
+			b.WriteString("        }\n")
+		}
+	}
+	b.WriteString("    }\n")
+	return b.String()
+}
+
+// kdlString quotes s as a KDL string.
+func kdlString(s string) string {
+	return `"` + strings.NewReplacer(`\`, `\\`, `"`, `\"`, "\n", `\n`).Replace(s) + `"`
+}

internal/netbox/client.go

@@ -105,6 +105,22 @@ func (c *Client) SearchAll(ctx context.Context, query string, opts SearchOptions
 	if opts.Kind != "" && opts.Kind != "device" && opts.Kind != "vm" {
 		return nil, fmt.Errorf("invalid host kind %q", opts.Kind)
 	}
+	filters := ""
+	if opts.Tag != "" {
+		filters += "&tag=" + url.QueryEscape(opts.Tag)
+	}
+	if opts.Cluster != "" {
+		ids, err := c.clusterIDs(ctx, opts.Cluster)
+		if err != nil {
+			return nil, fmt.Errorf("clusters: %w", err)
+		}
+		if len(ids) == 0 {
+			return nil, nil // no such cluster in this NetBox
+		}
+		for _, id := range ids {
+			filters += fmt.Sprintf("&cluster_id=%d", id)
+		}
+	}
 	var (
 		mu      sync.Mutex
 		results []HostEntry
@@ -116,7 +132,7 @@ func (c *Client) SearchAll(ctx context.Context, query string, opts SearchOptions
 		wg.Add(1)
 		go func() {
 			defer wg.Done()
-			devices, err := c.fetchAllDevices(ctx, query, opts.Tag)
+			devices, err := c.fetchAllDevices(ctx, query, filters)
 			mu.Lock()
 			defer mu.Unlock()
 			if err != nil {
@@ -131,7 +147,7 @@ func (c *Client) SearchAll(ctx context.Context, query string, opts SearchOptions
 		wg.Add(1)
 		go func() {
 			defer wg.Done()
-			vms, err := c.fetchAllVMs(ctx, query, opts.Tag)
+			vms, err := c.fetchAllVMs(ctx, query, filters)
 			mu.Lock()
 			defer mu.Unlock()
 			if err != nil {
@@ -231,15 +247,27 @@ func (c *Client) searchVMs(ctx context.Context, query, tag string) ([]HostEntry,
 	return entries, nil
 }
 
-func (c *Client) fetchAllDevices(ctx context.Context, query, tag string) ([]HostEntry, error) {
+// clusterIDs returns the IDs of the clusters named name (case-insensitive).
+func (c *Client) clusterIDs(ctx context.Context, name string) ([]int, error) {
+	var resp netboxListResponse[netboxCluster]
+	apiURL := fmt.Sprintf("%s/api/virtualization/clusters/?name__ie=%s&limit=50", c.baseURL, url.QueryEscape(name))
+	if err := c.get(ctx, apiURL, &resp); err != nil {
+		return nil, err
+	}
+	ids := make([]int, 0, len(resp.Results))
+	for _, cluster := range resp.Results {
+		ids = append(ids, cluster.ID)
+	}
+	return ids, nil
+}
+
+// fetchAllDevices pages through devices; filters are extra "&key=value" parameters.
+func (c *Client) fetchAllDevices(ctx context.Context, query, filters string) ([]HostEntry, error) {
 	const pageSize = 50
 	var all []HostEntry
 	for offset := 0; ; offset += pageSize {
 		apiURL := fmt.Sprintf("%s/api/dcim/devices/?name__ic=%s&limit=%d&offset=%d",
-			c.baseURL, url.QueryEscape(query), pageSize, offset)
-		if tag != "" {
-			apiURL += "&tag=" + url.QueryEscape(tag)
-		}
+			c.baseURL, url.QueryEscape(query), pageSize, offset) + filters
 		var resp netboxListResponse[netboxDevice]
 		if err := c.get(ctx, apiURL, &resp); err != nil {
 			return nil, err
@@ -254,15 +282,12 @@ func (c *Client) fetchAllDevices(ctx context.Context, query, tag string) ([]Host
 	return all, nil
 }
 
-func (c *Client) fetchAllVMs(ctx context.Context, query, tag string) ([]HostEntry, error) {
+func (c *Client) fetchAllVMs(ctx context.Context, query, filters string) ([]HostEntry, error) {
 	const pageSize = 50
 	var all []HostEntry
 	for offset := 0; ; offset += pageSize {
 		apiURL := fmt.Sprintf("%s/api/virtualization/virtual-machines/?name__ic=%s&limit=%d&offset=%d",
-			c.baseURL, url.QueryEscape(query), pageSize, offset)
-		if tag != "" {
-			apiURL += "&tag=" + url.QueryEscape(tag)
-		}
+			c.baseURL, url.QueryEscape(query), pageSize, offset) + filters
 		var resp netboxListResponse[netboxVM]
 		if err := c.get(ctx, apiURL, &resp); err != nil {
 			return nil, err
@@ -343,6 +368,9 @@ func deviceToEntry(d netboxDevice) HostEntry {
 	for _, t := range d.Tags {
 		e.Tags = append(e.Tags, t.Name)
 	}
+	if d.Cluster != nil {
+		e.Cluster = d.Cluster.Name
+	}
 	return e
 }
 
@@ -357,6 +385,9 @@ func vmToEntry(v netboxVM) HostEntry {
 	for _, t := range v.Tags {
 		e.Tags = append(e.Tags, t.Name)
 	}
+	if v.Cluster != nil {
+		e.Cluster = v.Cluster.Name
+	}
 	return e
 }
 

internal/netbox/client_test.go

@@ -235,7 +235,7 @@ func TestGetIPsWithFilter(t *testing.T) {
 	defer srv.Close()
 
 	c := NewClient(srv.URL, "token", 0)
-	ips, err := c.GetIPsWithFilter(context.Background(), "device_id=1&interface_name=mgmt0")
+	ips, err := c.GetIPsWithFilter(context.Background(), "device_id=1&interface=mgmt0")
 	if err != nil {
 		t.Fatalf("GetIPsWithFilter: %v", err)
 	}

internal/netbox/cluster_test.go

@@ -0,0 +1,51 @@
+package netbox
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestSearchAllByCluster(t *testing.T) {
+	var deviceQuery, vmQuery string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch r.URL.Path {
+		case "/api/virtualization/clusters/":
+			if r.URL.Query().Get("name__ie") == "PVE" {
+				fmt.Fprint(w, `{"count":2,"results":[{"id":3,"name":"pve"},{"id":4,"name":"pve"}]}`)
+				return
+			}
+			fmt.Fprint(w, `{"count":0,"results":[]}`)
+		case "/api/dcim/devices/":
+			deviceQuery = r.URL.RawQuery
+			fmt.Fprint(w, `{"count":1,"results":[{"id":1,"name":"node1","cluster":{"id":3,"name":"pve"}}]}`)
+		case "/api/virtualization/virtual-machines/":
+			vmQuery = r.URL.RawQuery
+			fmt.Fprint(w, `{"count":1,"results":[{"id":2,"name":"vm1","cluster":{"id":4,"name":"pve"}}]}`)
+		}
+	}))
+	defer srv.Close()
+	c := NewClient(srv.URL, "t", 1)
+
+	hosts, err := c.SearchAll(context.Background(), "", SearchOptions{Cluster: "PVE", Kind: "device"})
+	if err != nil || len(hosts) != 1 || hosts[0].Name != "node1" || hosts[0].Cluster != "pve" {
+		t.Fatalf("got %+v %v", hosts, err)
+	}
+	if want := "name__ic=&limit=50&offset=0&cluster_id=3&cluster_id=4"; deviceQuery != want {
+		t.Errorf("device query %q, want %q", deviceQuery, want)
+	}
+	if vmQuery != "" {
+		t.Error("VMs queried for kind device")
+	}
+	all, err := c.SearchAll(context.Background(), "", SearchOptions{Cluster: "PVE"})
+	if err != nil || len(all) != 2 {
+		t.Fatalf("all kinds: %+v %v", all, err)
+	}
+	none, err := c.SearchAll(context.Background(), "", SearchOptions{Cluster: "missing"})
+	if err != nil || len(none) != 0 {
+		t.Fatalf("unknown cluster: %+v %v", none, err)
+	}
+}

internal/netbox/models.go

@@ -7,6 +7,8 @@ import "strings"
 type SearchOptions struct {
 	Tag  string // filter by tag slug; empty = no filter
 	Kind string // "device" | "vm" | "" (both)
+	// Cluster filters SearchAll by virtualization cluster name (case-insensitive).
+	Cluster string
 }
 
 // HostEntry is a unified model for both devices and virtual machines from NetBox.
@@ -18,6 +20,13 @@ type HostEntry struct {
 	PrimaryIP4 string // e.g. "10.0.1.5" (prefix length stripped)
 	PrimaryIP6 string
 	Tags       []string
+	Cluster    string // virtualization cluster name, if assigned
+}
+
+// netboxCluster is the nested cluster of a device or virtual machine.
+type netboxCluster struct {
+	ID   int    `json:"id"`
+	Name string `json:"name"`
 }
 
 // netboxIP represents an IP address as returned by the NetBox API.
@@ -32,8 +41,9 @@ type netboxDevice struct {
 	Tags []struct {
 		Name string `json:"name"`
 	} `json:"tags"`
-	PrimaryIP4 *netboxIP `json:"primary_ip4"`
-	PrimaryIP6 *netboxIP `json:"primary_ip6"`
+	PrimaryIP4 *netboxIP      `json:"primary_ip4"`
+	PrimaryIP6 *netboxIP      `json:"primary_ip6"`
+	Cluster    *netboxCluster `json:"cluster"`
 }
 
 // netboxVM matches the relevant fields of the NetBox /virtualization/virtual-machines/ response.
@@ -43,8 +53,9 @@ type netboxVM struct {
 	Tags []struct {
 		Name string `json:"name"`
 	} `json:"tags"`
-	PrimaryIP4 *netboxIP `json:"primary_ip4"`
-	PrimaryIP6 *netboxIP `json:"primary_ip6"`
+	PrimaryIP4 *netboxIP      `json:"primary_ip4"`
+	PrimaryIP6 *netboxIP      `json:"primary_ip6"`
+	Cluster    *netboxCluster `json:"cluster"`
 }
 
 type netboxListResponse[T any] struct {

internal/netbox/sources_test.go

@@ -78,7 +78,7 @@ func TestMultiSourceSearchAndRouting(t *testing.T) {
 			if err != nil || len(ips) != 1 || ips[0] != tc.ip {
 				t.Fatalf("wrong IP source: %v, %v", ips, err)
 			}
-			ips, err = c.GetIPsWithFilterForHost(ctx, host, "device_id=1&interface_name=mgmt0")
+			ips, err = c.GetIPsWithFilterForHost(ctx, host, "device_id=1&interface=mgmt0")
 			if err != nil || len(ips) != 1 || ips[0] != tc.ip {
 				t.Fatalf("wrong interface source: %v, %v", ips, err)
 			}

internal/resolver/interface_name.go

@@ -16,13 +16,16 @@ type InterfaceNameStrategy struct {
 func (s *InterfaceNameStrategy) Name() string { return "interface_name" }
 
 func (s *InterfaceNameStrategy) Resolve(ctx context.Context, entry *netbox.HostEntry, client *netbox.Client) (string, error) {
-	// Build filter parameters for IP addresses attached to the named interface.
+	// NetBox filters IP addresses by interface name with interface= (devices)
+	// and vminterface= (VMs); unknown parameters would be ignored silently and
+	// return every address of the host. A missing interface is an HTTP 400,
+	// which lets the chain try the next strategy.
 	var filterParam string
 	switch entry.Kind {
 	case "device":
-		filterParam = fmt.Sprintf("device_id=%d&interface_name=%s", entry.ID, url.QueryEscape(s.name))
+		filterParam = fmt.Sprintf("device_id=%d&interface=%s", entry.ID, url.QueryEscape(s.name))
 	case "vm":
-		filterParam = fmt.Sprintf("virtual_machine_id=%d&vminterface_name=%s", entry.ID, url.QueryEscape(s.name))
+		filterParam = fmt.Sprintf("virtual_machine_id=%d&vminterface=%s", entry.ID, url.QueryEscape(s.name))
 	default:
 		return "", fmt.Errorf("unknown kind %q", entry.Kind)
 	}

internal/resolver/interface_name_test.go

@@ -0,0 +1,56 @@
+package resolver
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/netbox"
+)
+
+// NetBox ignores unknown filters, so the strategy must use the real filter
+// names; otherwise it silently returns the host's first address.
+func TestInterfaceNameStrategyFilters(t *testing.T) {
+	for kind, want := range map[string]string{
+		"device": "device_id=7&interface=mgmt0",
+		"vm":     "virtual_machine_id=7&vminterface=mgmt0",
+	} {
+		var got string
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			q := r.URL.Query()
+			q.Del("limit")
+			q.Del("offset")
+			got = q.Encode()
+			w.Header().Set("Content-Type", "application/json")
+			w.Write([]byte(`{"count":1,"results":[{"address":"10.0.0.7/24"}]}`))
+		}))
+		ip, err := (&InterfaceNameStrategy{name: "mgmt0"}).Resolve(context.Background(), &netbox.HostEntry{ID: 7, Kind: kind}, netbox.NewClient(srv.URL, "t", 1))
+		srv.Close()
+		if err != nil || ip != "10.0.0.7" {
+			t.Fatalf("%s: %q %v", kind, ip, err)
+		}
+		if parsed, _ := urlQuery(want); got != parsed {
+			t.Errorf("%s: query %q, want %q", kind, got, parsed)
+		}
+	}
+}
+
+func TestInterfaceNameStrategyMissingInterfaceFallsThrough(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, `{"vminterface":["Select a valid choice."]}`, http.StatusBadRequest)
+	}))
+	defer srv.Close()
+	client := netbox.NewClient(srv.URL, "t", 1)
+	chain := &Chain{strategies: []Strategy{&InterfaceNameStrategy{name: "mgmt0"}, &PrimaryIPStrategy{}}}
+	ip, err := chain.Resolve(context.Background(), &netbox.HostEntry{ID: 7, Kind: "vm", PrimaryIP4: "10.0.0.9"}, client)
+	if err != nil || ip != "10.0.0.9" {
+		t.Fatalf("got %q %v", ip, err)
+	}
+}
+
+func urlQuery(s string) (string, error) {
+	q, err := url.ParseQuery(s)
+	return q.Encode(), err
+}

internal/setup/multi.go

@@ -0,0 +1,128 @@
+package setup
+
+import (
+	"errors"
+	"fmt"
+	"sort"
+	"strconv"
+	"strings"
+
+	"charm.land/huh/v2"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
+)
+
+func editMulti(cfg *config.Config) error {
+	multiplexer := cfg.Multi.Multiplexer
+	if multiplexer == "" {
+		multiplexer = "auto"
+	}
+	perWindow := ""
+	if cfg.Multi.PanesPerWindow > 0 {
+		perWindow = strconv.Itoa(cfg.Multi.PanesPerWindow)
+	}
+	groups := formatGroups(cfg.Groups)
+	syncKey, soloKey := cfg.Multi.SyncKey, cfg.Multi.SoloKey
+	validKey := func(field string) func(string) error {
+		return func(s string) error {
+			candidate := config.Config{Multi: cfg.Multi}
+			if field == "sync" {
+				candidate.Multi.SyncKey = strings.TrimSpace(s)
+			} else {
+				candidate.Multi.SoloKey = strings.TrimSpace(s)
+			}
+			return candidate.ValidateMulti()
+		}
+	}
+	err := huh.NewForm(huh.NewGroup(
+		huh.NewSelect[string]().
+			Title("Multiplexer").
+			Description("netssh multi opens hosts side by side. auto uses the one you are in, else tmux, else zellij.").
+			Options(huh.NewOption("auto", "auto"), huh.NewOption("tmux", "tmux"), huh.NewOption("zellij", "zellij")).
+			Value(&multiplexer),
+		huh.NewInput().
+			Title("Panes per window").
+			Description(fmt.Sprintf("More hosts open in further windows or tabs. Leave empty for %d.", config.DefaultPanesPerWindow)).
+			Value(&perWindow).
+			Validate(func(s string) error {
+				if s = strings.TrimSpace(s); s == "" {
+					return nil
+				}
+				if n, err := strconv.Atoi(s); err != nil || n < 1 || n > 64 {
+					return errors.New("must be a number between 1 and 64")
+				}
+				return nil
+			}),
+		huh.NewInput().
+			Title("tmux key: broadcast to all panes").
+			Description(fmt.Sprintf("Pressed after the tmux prefix. Empty = %s, none = no key.", config.DefaultSyncKey)).
+			Placeholder(config.DefaultSyncKey).
+			Value(&syncKey).
+			Validate(validKey("sync")),
+		huh.NewInput().
+			Title("tmux key: exclude/include this pane").
+			Description(fmt.Sprintf("Pressed after the tmux prefix. Empty = %s, none = no key.", config.DefaultSoloKey)).
+			Placeholder(config.DefaultSoloKey).
+			Value(&soloKey).
+			Validate(validKey("solo")),
+		huh.NewText().
+			Title("Groups").
+			Description("One per line: NAME: host, tag:TAG, cluster:NAME, @other — open with netssh multi @NAME.").
+			Lines(4).
+			Value(&groups).
+			Validate(func(s string) error {
+				_, err := parseGroups(s)
+				return err
+			}),
+	).Title("Multi-session")).Run()
+	if err != nil {
+		return err
+	}
+	cfg.Multi.Multiplexer = multiplexer
+	if multiplexer == "auto" {
+		cfg.Multi.Multiplexer = ""
+	}
+	cfg.Multi.PanesPerWindow, _ = strconv.Atoi(strings.TrimSpace(perWindow))
+	cfg.Multi.SyncKey = strings.TrimSpace(syncKey)
+	cfg.Multi.SoloKey = strings.TrimSpace(soloKey)
+	cfg.Groups, _ = parseGroups(groups)
+	return nil
+}
+
+// parseGroups reads "NAME: sel1, sel2" lines into groups:.
+func parseGroups(s string) (map[string][]string, error) {
+	var out map[string][]string
+	for _, line := range parseLines(s) {
+		name, members, ok := strings.Cut(line, ":")
+		name = strings.ToLower(strings.TrimSpace(name))
+		// "tag:x" alone has no group name before the first colon worth keeping.
+		if !ok || name == "" || name == "tag" || name == "cluster" {
+			return nil, fmt.Errorf("%q: expected NAME: host, tag:TAG, …", line)
+		}
+		var selectors []string
+		for _, field := range strings.FieldsFunc(members, func(r rune) bool { return r == ',' || r == ' ' || r == '\t' }) {
+			selectors = append(selectors, field)
+		}
+		if out == nil {
+			out = make(map[string][]string)
+		}
+		out[name] = append(out[name], selectors...)
+	}
+	if err := (&config.Config{Groups: out}).ValidateMulti(); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func formatGroups(groups map[string][]string) string {
+	names := make([]string, 0, len(groups))
+	for name := range groups {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	lines := make([]string, 0, len(names))
+	for _, name := range names {
+		lines = append(lines, name+": "+strings.Join(groups[name], ", "))
+	}
+	return strings.Join(lines, "\n")
+}

internal/setup/wizard.go

@@ -91,6 +91,7 @@ func runMenu(cfg *config.Config) error {
 				huh.NewOption("SSH options — jump host, host keys, target, -o, forwards", "ssh"),
 				huh.NewOption(fmt.Sprintf("SSH rules — per tag, instance, kind, name (%d)", len(cfg.SSH.Rules)), "rules"),
 				huh.NewOption(fmt.Sprintf("Static hosts — hosts not in NetBox (%d)", len(cfg.Hosts)), "hosts"),
+				huh.NewOption(fmt.Sprintf("Multi-session — groups, tmux/zellij (%d groups)", len(cfg.Groups)), "multi"),
 				huh.NewOption("Resolver & cache", "resolver"),
 				huh.NewOption("Shortcuts & command alias", "shortcuts"),
 				huh.NewOption("Completion", "completion"),
@@ -115,6 +116,8 @@ func runMenu(cfg *config.Config) error {
 			if hosts, err = configureHosts(cfg.Hosts); err == nil {
 				cfg.Hosts = hosts
 			}
+		case "multi":
+			err = editMulti(cfg)
 		case "resolver":
 			err = editResolverCache(cfg)
 		case "shortcuts":
@@ -369,6 +372,9 @@ func save(cfg config.Config) error {
 	if err := cfg.ValidateHosts(); err != nil {
 		return err
 	}
+	if err := cfg.ValidateMulti(); err != nil {
+		return err
+	}
 	path := config.Path()
 	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
 		return fmt.Errorf("creating config dir: %w", err)
@@ -461,6 +467,36 @@ func save(cfg config.Config) error {
 		}
 	}
 
+	if len(cfg.Groups) > 0 {
+		b.WriteString("\ngroups:\n")
+		names := make([]string, 0, len(cfg.Groups))
+		for name := range cfg.Groups {
+			names = append(names, name)
+		}
+		sort.Strings(names)
+		for _, name := range names {
+			quoted := make([]string, 0, len(cfg.Groups[name]))
+			for _, selector := range cfg.Groups[name] {
+				quoted = append(quoted, strconv.Quote(selector))
+			}
+			fmt.Fprintf(&b, "  %s: [%s]\n", name, strings.Join(quoted, ", "))
+		}
+	}
+	if cfg.Multi != (config.MultiConfig{}) {
+		b.WriteString("\nmulti:\n")
+		if cfg.Multi.Multiplexer != "" {
+			fmt.Fprintf(&b, "  multiplexer: %s\n", cfg.Multi.Multiplexer)
+		}
+		if cfg.Multi.PanesPerWindow > 0 {
+			fmt.Fprintf(&b, "  panes_per_window: %d\n", cfg.Multi.PanesPerWindow)
+		}
+		for _, key := range [][2]string{{"sync_key", cfg.Multi.SyncKey}, {"solo_key", cfg.Multi.SoloKey}} {
+			if key[1] != "" {
+				fmt.Fprintf(&b, "  %s: %q\n", key[0], key[1])
+			}
+		}
+	}
+
 	if cfg.Completion.MaxResults > 0 {
 		fmt.Fprintf(&b, "\ncompletion:\n  max_results: %d\n", cfg.Completion.MaxResults)
 	}

internal/setup/wizard_test.go

@@ -617,3 +617,37 @@ func TestValidateHostIn(t *testing.T) {
 		t.Fatal("invalid address accepted")
 	}
 }
+
+func TestParseGroupsAndSaveMulti(t *testing.T) {
+	groups, err := parseGroups("K8s: master1, tag:k8s-worker\npve: cluster:pve-fsn1 @k8s\n")
+	want := map[string][]string{"k8s": {"master1", "tag:k8s-worker"}, "pve": {"cluster:pve-fsn1", "@k8s"}}
+	if err != nil || !reflect.DeepEqual(groups, want) {
+		t.Fatalf("got %v %v", groups, err)
+	}
+	if again, _ := parseGroups(formatGroups(groups)); !reflect.DeepEqual(again, want) {
+		t.Fatalf("roundtrip: %v", again)
+	}
+	for _, bad := range []string{"no colon", "tag:x", "bad name: a", "empty:"} {
+		if _, err := parseGroups(bad); err == nil {
+			t.Errorf("%q accepted", bad)
+		}
+	}
+
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("HOME", t.TempDir())
+	cfg := config.Config{
+		Hosts:  []config.StaticHost{{Name: "a", Address: "10.0.0.1"}},
+		Groups: groups,
+		Multi:  config.MultiConfig{Multiplexer: "zellij", PanesPerWindow: 4},
+	}
+	if err := save(cfg); err != nil {
+		t.Fatal(err)
+	}
+	loaded, err := config.Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(loaded.Groups, want) || loaded.Multi != cfg.Multi {
+		t.Fatalf("got %v %+v", loaded.Groups, loaded.Multi)
+	}
+}

internal/shortcuts/shortcuts.go

@@ -59,6 +59,11 @@ func MakeNormalizer(cfg config.ShortcutsConfig) func(string) string {
 // It normalizes the name (strips configured domains, applies rewrites, optionally strips hyphens) then
 // replaces any remaining dots with underscores so the result is a valid identifier.
 func AliasName(name string, cfg config.ShortcutsConfig) string {
-	s := Normalize(name, cfg)
+	// Shorten only the hostname: anchored rewrite rules must not see "instance/".
+	prefix := ""
+	if source, host, ok := strings.Cut(name, "/"); ok {
+		prefix, name = strings.ToLower(source)+"_", host
+	}
+	s := prefix + Normalize(name, cfg)
 	return strings.NewReplacer(".", "_", "/", "_").Replace(s)
 }

internal/shortcuts/shortcuts_test.go

@@ -115,3 +115,13 @@ func TestNormalizeRewritesOrder(t *testing.T) {
 		t.Fatalf("got %q", got)
 	}
 }
+
+func TestAliasNameRewritesInstanceQualifiedHosts(t *testing.T) {
+	cfg := config.ShortcutsConfig{
+		Domains:  []string{".hoster.test"},
+		Rewrites: []config.ShortcutRewrite{{Pattern: `^([a-z]+)[0-9]+-`, Replace: "$1"}},
+	}
+	if got := shortcuts.AliasName("fsn/fsn1-pve1.hoster.test", cfg); got != "fsn_fsnpve1" {
+		t.Fatalf("got %q", got)
+	}
+}

internal/ssh/args.go

@@ -59,7 +59,7 @@ func (c Client) Parse(args []string) *ParsedArgs {
 func (c Client) parsed(args []string, i int) *ParsedArgs {
 	dest, path := args[i], ""
 	if c.paths {
-		if d, p, remote := splitRemote(dest); remote {
+		if d, p, remote := c.splitRemote(dest); remote {
 			dest, path = d, p
 		}
 	}
@@ -88,7 +88,7 @@ func (c Client) replaceHost(args []string, dests []int, newHost string) []string
 			prefix, original = original[:at+1], original[at+1:]
 		}
 		if c.paths {
-			if _, path, remote := splitRemote(original); remote {
+			if _, path, remote := c.splitRemote(original); remote {
 				suffix = ":" + path
 			}
 		}

internal/ssh/client.go

@@ -13,6 +13,18 @@ type Client struct {
 	port    byte          // flag for the port: -p (ssh) or -P (sftp, scp)
 	user    byte          // flag for the login user; 0 when only user@ or -o User work
 	paths   bool          // destinations are host[:path]
+	// instances are the configured NetBox instance names; "inst/host:path"
+	// is remote only for these, so local paths like "dir/file:x" stay local.
+	instances map[string]bool
+}
+
+// WithInstances returns c aware of the NetBox instance prefixes in host:path.
+func (c Client) WithInstances(names []string) Client {
+	c.instances = make(map[string]bool, len(names))
+	for _, name := range names {
+		c.instances[strings.ToLower(name)] = true
+	}
+	return c
 }
 
 var (
@@ -61,7 +73,7 @@ func (c Client) Operands(args []string) ([]Operand, error) {
 		if strings.HasPrefix(arg, "scp://") || strings.HasPrefix(arg, "sftp://") {
 			return nil, fmt.Errorf("%q: use host:path instead of a URI", arg)
 		}
-		dest, path, remote := splitRemote(arg)
+		dest, path, remote := c.splitRemote(arg)
 		if !remote {
 			continue
 		}
@@ -105,9 +117,22 @@ func (c Client) insertionPoint(args []string) int {
 	return len(args)
 }
 
-// splitRemote mirrors scp's colon(): an argument is remote when a ':' comes
+// splitRemote is splitHostPath with netssh's [user@]instance/host:path form.
+func (c Client) splitRemote(arg string) (dest, path string, remote bool) {
+	if head, rest, ok := strings.Cut(arg, "/"); ok {
+		instance := head[strings.LastIndex(head, "@")+1:]
+		if c.instances[strings.ToLower(instance)] {
+			if d, p, r := splitHostPath(rest); r {
+				return head + "/" + d, p, true
+			}
+		}
+	}
+	return splitHostPath(arg)
+}
+
+// splitHostPath mirrors scp's colon(): an argument is remote when a ':' comes
 // before any '/'. A leading "[" starts a bracketed IPv6 address.
-func splitRemote(arg string) (dest, path string, remote bool) {
+func splitHostPath(arg string) (dest, path string, remote bool) {
 	if strings.HasPrefix(arg, "/") || strings.HasPrefix(arg, ".") {
 		return "", "", false
 	}

internal/ssh/client_test.go

@@ -154,3 +154,27 @@ func TestApplyInsertsOptionsBeforeDoubleDash(t *testing.T) {
 		t.Fatalf("got %v, want %v", got, want)
 	}
 }
+
+// Instance-qualified hosts contain "/" before the ":" of host:path; only
+// configured instances make such an argument remote.
+func TestInstanceQualifiedHostPath(t *testing.T) {
+	scp := SCP.WithInstances([]string{"prod"})
+	ops, err := scp.Operands([]string{"a.txt", "ops@prod/web01:/tmp/", "dir/file:x"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := []Operand{{Idx: 1, User: "ops", Host: "prod/web01", Path: "/tmp/"}}; !reflect.DeepEqual(ops, want) {
+		t.Fatalf("got %+v", ops)
+	}
+	got := scp.Apply([]string{"a.txt", "ops@prod/web01:/tmp/"}, []int{1}, Host{Name: "web01", IP: "192.0.2.1"}, config.SSHOptions{}, WrapperFlags{}).Args
+	if want := []string{"a.txt", "ops@192.0.2.1:/tmp/"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("apply: %v", got)
+	}
+	sftp := SFTP.WithInstances([]string{"prod"})
+	if p := sftp.Parse([]string{"prod/web01:/var/log"}); p == nil || p.Host != "prod/web01" || p.Path != "/var/log" {
+		t.Fatalf("sftp: %+v", p)
+	}
+	if ops, _ := SCP.Operands([]string{"prod/web01:/tmp/", "."}); len(ops) != 0 {
+		t.Fatalf("unknown instance must stay local: %+v", ops)
+	}
+}

internal/tui/model.go

@@ -27,8 +27,9 @@ type SelectedHost struct {
 	IP       string
 	User     string   // empty = use config default
 	Port     string   // empty = use default port
-	Action   string   // ActionSSH, ActionSFTP, or ActionTunnel
+	Action   string   // ActionSSH, ActionSFTP, ActionTunnel, or ActionMulti
 	Forwards []string // forward names or specs for ActionTunnel
+	Targets  []string // marked hosts for ActionMulti
 }
 
 // Actions the user can start on a host.
@@ -36,6 +37,7 @@ const (
 	ActionSSH    = ""
 	ActionSFTP   = "sftp"
 	ActionTunnel = "tunnel"
+	ActionMulti  = "multi"
 )
 
 // --- bubbletea messages ---
@@ -74,7 +76,8 @@ func (h hostItem) FilterValue() string { return h.name }
 
 // --- compact list delegate ---
 
-type compactDelegate struct{}
+// compactDelegate shares the model's marks so marked hosts show a dot.
+type compactDelegate struct{ marked map[string]bool }
 
 func (d compactDelegate) Height() int                             { return 1 }
 func (d compactDelegate) Spacing() int                            { return 0 }
@@ -84,7 +87,11 @@ func (d compactDelegate) Render(w io.Writer, m list.Model, index int, item list.
 	if !ok {
 		return
 	}
-	line := fmt.Sprintf("  %s  %s", h.name, lipgloss.NewStyle().Foreground(lipgloss.Color("240")).Render(h.ip))
+	mark := "  "
+	if d.marked[h.key()] {
+		mark = "● "
+	}
+	line := fmt.Sprintf("  %s%s  %s", mark, h.name, lipgloss.NewStyle().Foreground(lipgloss.Color("240")).Render(h.ip))
 	if index == m.Index() {
 		line = lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("86")).Render("> " + strings.TrimPrefix(line, "  "))
 	}
@@ -169,10 +176,12 @@ type Model struct {
 	selected                       *SelectedHost
 	width                          int
 	height                         int
-	recentMode                     bool // true when showing recent hosts (empty search, initial state)
-	filterOpen                     bool // Ctrl+F toggles
-	editMode                       bool // Ctrl+E on the selected item
-	forwardMode                    bool // Ctrl+T on the selected item
+	recentMode                     bool            // true when showing recent hosts (empty search, initial state)
+	filterOpen                     bool            // Ctrl+F toggles
+	editMode                       bool            // Ctrl+E on the selected item
+	forwardMode                    bool            // Ctrl+T on the selected item
+	marked                         map[string]bool // hostItem.key() of hosts marked with space
+	markOrder                      []string        // targets in the order they were marked
 }
 
 func New(client *netbox.Client, c *cache.Cache, defaultUser string, defaultPorts ...int) *Model {
@@ -191,7 +200,8 @@ func New(client *netbox.Client, c *cache.Cache, defaultUser string, defaultPorts
 	fwd.Prompt = ""
 	fwd.Placeholder = "web, 8080:localhost:80"
 
-	l := list.New(nil, compactDelegate{}, 0, 0)
+	marked := make(map[string]bool)
+	l := list.New(nil, compactDelegate{marked: marked}, 0, 0)
 	l.SetShowHelp(false)
 	l.SetShowTitle(false)
 	l.SetShowStatusBar(false)
@@ -212,6 +222,7 @@ func New(client *netbox.Client, c *cache.Cache, defaultUser string, defaultPorts
 		filterInput:  fi,
 		editInput:    ei,
 		forwardInput: fwd,
+		marked:       marked,
 		list:         l,
 		client:       client,
 		cache:        c,
@@ -386,11 +397,26 @@ func (m *Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			return m, nil
 
 		case "enter":
+			if len(m.markOrder) > 0 {
+				m.selected = &SelectedHost{Action: ActionMulti, Targets: append([]string(nil), m.markOrder...)}
+				return m, tea.Quit
+			}
 			if item, ok := m.list.SelectedItem().(hostItem); ok {
 				m.selected = &SelectedHost{Name: item.name, IP: item.ip, Kind: item.kind}
 				return m, tea.Quit
 			}
 
+		case "space":
+			if item, ok := m.list.SelectedItem().(hostItem); ok {
+				m.toggleMark(item)
+				m.list.CursorDown()
+				return m, nil
+			}
+
+		case "ctrl+a":
+			m.toggleAllVisible()
+			return m, nil
+
 		case "ctrl+e":
 			if item, ok := m.list.SelectedItem().(hostItem); ok {
 				m.openEdit(item)
@@ -584,7 +610,10 @@ func (m *Model) viewContent() string {
 		sb.WriteString(m.editInput.View() + "\n")
 		sb.WriteString(lipgloss.NewStyle().Foreground(lipgloss.Color("240")).Render("  enter connect  esc cancel") + "\n")
 	} else {
-		hint := "ctrl+c quit  enter connect  ctrl+o sftp  ctrl+t forward  ctrl+e edit  ctrl+f filter  ctrl+n notes  ctrl+b NetBox"
+		hint := "ctrl+c quit  enter connect  space mark  ctrl+o sftp  ctrl+t forward  ctrl+e edit  ctrl+f filter  ctrl+n notes  ctrl+b NetBox"
+		if n := len(m.markOrder); n > 0 {
+			hint = fmt.Sprintf("%d marked — enter open side by side  space unmark  ctrl+a all  esc quit", n)
+		}
 		sb.WriteString("\n" + lipgloss.NewStyle().Foreground(lipgloss.Color("240")).Render(hint) + "\n")
 	}
 
@@ -724,6 +753,42 @@ func (m *Model) buildSelected(item hostItem) *SelectedHost {
 
 func (m *Model) SetNotes(service *notes.Service) { m.noteService = service }
 
+func (h hostItem) key() string { return h.name + "\x00" + h.kind }
+
+// toggleMark marks or unmarks a host for opening several side by side.
+func (m *Model) toggleMark(item hostItem) {
+	key := item.key()
+	if m.marked[key] {
+		delete(m.marked, key)
+		for i, target := range m.markOrder {
+			if target == item.name {
+				m.markOrder = append(m.markOrder[:i], m.markOrder[i+1:]...)
+				break
+			}
+		}
+		return
+	}
+	m.marked[key] = true
+	m.markOrder = append(m.markOrder, item.name)
+}
+
+// toggleAllVisible marks every listed host, or unmarks them if all are marked.
+func (m *Model) toggleAllVisible() {
+	var items []hostItem
+	allMarked := true
+	for _, it := range m.list.Items() {
+		if item, ok := it.(hostItem); ok {
+			items = append(items, item)
+			allMarked = allMarked && m.marked[item.key()]
+		}
+	}
+	for _, item := range items {
+		if m.marked[item.key()] == allMarked {
+			m.toggleMark(item)
+		}
+	}
+}
+
 // SetForwards provides the forward names configured for a host (ctrl+t).
 func (m *Model) SetForwards(forwardsFor func(name, kind string, tags []string) []string) {
 	m.forwardsFor = forwardsFor

internal/tui/model_test.go

@@ -122,3 +122,38 @@ func TestForwardInputEscCancels(t *testing.T) {
 		t.Fatal("esc did not cancel")
 	}
 }
+
+func TestSpaceMarksHostsAndEnterOpensThem(t *testing.T) {
+	m := New(nil, nil, "")
+	m.updateListItems([]netbox.HostEntry{{Name: "a", Kind: "device"}, {Name: "b", Kind: "device"}, {Name: "c", Kind: "vm"}})
+	m.Update(tea.KeyPressMsg{Code: tea.KeySpace, Text: " "})
+	if len(m.markOrder) != 1 || m.markOrder[0] != "a" || m.list.Index() != 1 {
+		t.Fatalf("space: marks %v, cursor %d", m.markOrder, m.list.Index())
+	}
+	if m.input.Value() != "" {
+		t.Fatal("space went into the search field")
+	}
+	m.list.Select(2)
+	m.Update(tea.KeyPressMsg{Code: tea.KeySpace, Text: " "})
+	if !strings.Contains(m.viewContent(), "2 marked") {
+		t.Fatalf("no marked count:\n%s", m.viewContent())
+	}
+	m.Update(tea.KeyPressMsg{Code: tea.KeyEnter})
+	if m.selected == nil || m.selected.Action != ActionMulti || !reflect.DeepEqual(m.selected.Targets, []string{"a", "c"}) {
+		t.Fatalf("got %+v", m.selected)
+	}
+}
+
+func TestCtrlATogglesAllVisible(t *testing.T) {
+	m := New(nil, nil, "")
+	m.updateListItems([]netbox.HostEntry{{Name: "a"}, {Name: "b"}})
+	m.toggleMark(hostItem{name: "a"})
+	m.Update(tea.KeyPressMsg{Code: 'a', Mod: tea.ModCtrl})
+	if !reflect.DeepEqual(m.markOrder, []string{"a", "b"}) {
+		t.Fatalf("mark all: %v", m.markOrder)
+	}
+	m.Update(tea.KeyPressMsg{Code: 'a', Mod: tea.ModCtrl})
+	if len(m.markOrder) != 0 {
+		t.Fatalf("unmark all: %v", m.markOrder)
+	}
+}

testenv/README.md

@@ -0,0 +1,116 @@
+# netssh test environment
+
+A local Docker environment for testing every netssh feature against real
+services: two NetBox instances, SSH targets on three networks, a jump host,
+and a client with ssh, sftp, scp, tmux, zellij, bash, zsh, and fish. It is for
+local use only and is not part of CI/CD.
+
+```sh
+testenv/up.sh            # build, start, seed NetBox (first start ~6 min, then ~1 min)
+testenv/test.sh          # run all tests; testenv/test.sh tunnel runs only matching files
+testenv/shell.sh         # interactive shell in the client, netssh configured
+testenv/down.sh          # stop and delete everything (volumes, generated state)
+```
+
+`test.sh` rebuilds the client image first, so the tests always run the current
+source. `NO_BUILD=1 testenv/test.sh` skips that. Exit code 1 if any check fails.
+
+Requirements: Docker with Compose v2, about 3 GB RAM, ports 18000/18001 on
+127.0.0.1 free.
+
+## Topology
+
+```
+public 10.231.0.0/24 + fd00:30::/64   mgmt 10.231.1.0/24           prod 10.231.2.0/24
+ client .10 ────────────┬─ bastion .30 ───────────────────────────────┬─ (only via bastion)
+ netbox-fsn .20         │                 fsn1-pve1..3 .11-.13 (mgmt0) │  fsn1-pve1..3 .11-.13 (eth0)
+ netbox-lab .21         │                 lab-db1 .41, lab-web1 .42    │  web1 .21, web2 .22
+ legacy-box .50         client .10 ───────┘
+ v6-host fd00:30::60
+```
+
+| NetBox | Host | Kind | Primary IP | Other | Tags |
+|---|---|---|---|---|---|
+| fsn | `fsn1-pve1..3.hoster.test` | device, cluster `pve-fsn1` | eth0 = prod (needs bastion) | mgmt0 = mgmt (direct) | `pve` |
+| fsn | `bastion.hoster.test` | device | 10.231.0.30 | | `bastion` |
+| fsn | `v6-host` | device | fd00:30::60 (IPv6 only) | | `ipv6` |
+| fsn | `web1`, `web2` | VM, cluster `pve-fsn1` | prod (needs bastion) | | `web` |
+| lab | `lab-db1` | device | 10.231.1.41 | | `db` |
+| lab | `web1` | VM, cluster `lab-k8s` | 10.231.1.42 | | `web` |
+| — | `legacy-box` (10.231.0.50) | static host | | | |
+
+- **fsn** uses a v2 token (`nbt_…`), **lab** a legacy v1 token; both come from `.state/env`.
+- `web1` exists in both instances (ambiguity, `instance/host`).
+- Docker DNS resolves the `*.hoster.test` names on the mgmt network (`hostname` strategy).
+- Every target runs sshd on ports 22 and 2222 with users `ops` and `admin`, and an HTTP server on its own 127.0.0.1:8081 for tunnel tests ("hello from HOST").
+- NetBox UI: http://127.0.0.1:18000 (fsn), http://127.0.0.1:18001 (lab), login `admin` / `admin`.
+
+## Files
+
+| Path | Purpose |
+|---|---|
+| `compose.yaml` | All services and networks. |
+| `client.Dockerfile`, `client-entrypoint.sh` | Client image; builds netssh from the repository. |
+| `targets/` | SSH target image (sshd config, entrypoint). |
+| `seed/seed.py` | Fills both NetBox instances via the REST API (idempotent), writes `.state/`. |
+| `tests/run.sh`, `tests/lib.sh` | Test runner and helpers (`check`, `expect_out`, `expect_eq`, `expect_fail`, `wait_for`). |
+| `tests/NN-*.sh` | Test files; each runs in a fresh `HOME`. |
+| `tests/drive.py` | Drives `netssh configure` in huh's accessible mode. |
+| `.keys/`, `.state/` | Generated test key and seed output (git-ignored). |
+| `.artifacts/` | Screenshots from `tests/16-render.sh` (git-ignored). |
+
+## Writing tests
+
+Each `tests/NN-name.sh` is sourced by `run.sh` in a subshell with a new
+`HOME`, `XDG_CONFIG_HOME`, and `XDG_CACHE_HOME`. Write the netssh config with
+`config <<'EOF' … EOF` (both NetBox instances plus your YAML) or `config_only`
+(no NetBox), then use the helpers:
+
+```sh
+config <<'EOF'
+ssh: {default_user: ops}
+EOF
+expect_eq   "connect"   "fsn1-pve1" netssh fsn/fsn1-pve1.hoster.test hostname
+expect_out  "dry run"   "-J ops@10.231.0.30" netssh --dry-run fsn/web1
+expect_fail "ambiguous" "found 2 exact matches" netssh web1
+```
+
+ssh always reads `/home/tester/.ssh/config` (OpenSSH ignores `$HOME`): it uses
+the test key, `BatchMode`, `StrictHostKeyChecking accept-new`, and
+`LogLevel ERROR`. Tests that need their own known_hosts set
+`ssh.options.UserKnownHostsFile`. The TUI test runs netssh inside tmux and
+reads the screen with `tmux capture-pane`. The multi test (`15-multi.sh`)
+opens panes in real tmux and zellij sessions and checks that broadcast typing
+reaches every node.
+
+## What a user sees: `16-render.sh`
+
+The render test runs tmux, zellij, and the TUI in a real terminal emulator —
+xterm on a virtual X server (Xvfb) — takes screenshots, and reads them back
+with OCR (tesseract). It checks what is actually drawn: remote prompts in all
+panes, borders and titles with the host names, `[SYNC]` appearing and
+disappearing, panes side by side, broadcast output in every pane, input in one
+pane only without broadcast, the status bar, and the TUI marks. The broadcast
+keys are pressed as a user would: `tmux send-keys -K` delivers them to the
+xterm client, so they pass through the prefix and key tables (`prefix e` →
+`[SOLO]` and the pane drops out of the broadcast; `prefix S` toggles all panes;
+other windows stay unaffected).
+
+```sh
+testenv/test.sh render          # then look at the screenshots:
+ls testenv/.artifacts/          # tmux-1.png, zellij-2.png, tui-3.png, …
+```
+
+Helpers in `lib.sh`: `start_screen`/`stop_screen`, `term CMD…` (full-screen
+xterm), `shot NAME`, `screen_shows NAME TEXT…`, `screen_count NAME TEXT`.
+OCR reads each screenshot in three preprocessing variants (plain, stretched for
+dim gray, brightest channel for colored text) and normalizes characters it
+confuses in DejaVu Sans Mono (`1`/`l`, `C`/`(`), so checks stay robust without
+becoming vague.
+
+## Not covered
+
+- The installer (`install.sh`) downloads release assets from Gitea; it is tested by the Go tests with local fixtures.
+- macOS paths and behaviour.
+- `netssh uninstall` runs only with `--dry-run`, so the client keeps its binary.
+- Rendering is checked in xterm with DejaVu Sans Mono. Other terminals and fonts may differ, e.g. zellij's Powerline arrows need a Nerd Font.

testenv/client-entrypoint.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+# ssh reads ~/.ssh from the passwd entry, not $HOME, so the key and ssh config
+# live in /home/tester for every test; tests isolate netssh via HOME/XDG_*.
+set -eu
+mkdir -p /home/tester/.ssh
+if [ -f /keys/id_ed25519 ]; then
+  install -m 600 /keys/id_ed25519 /home/tester/.ssh/id_ed25519
+fi
+cat >/home/tester/.ssh/config <<'EOF'
+Host *
+  IdentityFile ~/.ssh/id_ed25519
+  IdentitiesOnly yes
+  BatchMode yes
+  ConnectTimeout 5
+  StrictHostKeyChecking accept-new
+  LogLevel ERROR
+EOF
+chmod 700 /home/tester/.ssh
+chmod 600 /home/tester/.ssh/config
+exec "$@"

testenv/client.Dockerfile

@@ -0,0 +1,26 @@
+# Client for the netssh test environment: netssh built from this repository
+# plus everything it drives or integrates with (ssh, sftp, scp, tmux, zellij,
+# bash, zsh, fish). Rebuild after code changes: testenv/up.sh or
+# docker compose -f testenv/compose.yaml build client
+FROM golang:1.27.4-alpine3.23 AS build
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY cmd ./cmd
+COPY internal ./internal
+RUN CGO_ENABLED=0 go build -o /out/netssh ./cmd/netssh
+
+FROM alpine:3.23
+# xvfb/xterm/imagemagick/tesseract: render panes in a real terminal emulator,
+# take screenshots, and read them back with OCR (tests/16-render.sh).
+RUN apk add --no-cache openssh-client-default tmux zellij bash zsh fish bash-completion \
+      curl python3 jq ncurses coreutils grep \
+      xvfb xterm imagemagick tesseract-ocr tesseract-ocr-data-eng font-dejavu \
+ && adduser -D -s /bin/bash tester
+COPY --from=build /out/netssh /usr/local/bin/netssh
+COPY testenv/client-entrypoint.sh /entrypoint.sh
+USER tester
+WORKDIR /home/tester
+ENV TERM=xterm-256color LANG=C.UTF-8
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["sleep", "infinity"]

testenv/compose.yaml

@@ -0,0 +1,211 @@
+# netssh test environment — local only, not used by CI/CD. See testenv/README.md.
+#
+#   public 10.231.0.0/24 + fd00:30::/64   client, NetBox x2, bastion, static host, IPv6 host
+#   mgmt   10.231.1.0/24                  client, Proxmox nodes (mgmt0), lab hosts
+#   prod   10.231.2.0/24                  bastion, Proxmox nodes (eth0), VMs — not reachable from the client
+name: netssh-test
+
+x-netbox: &netbox
+  image: netboxcommunity/netbox:v4.7.4-5.1.1
+  depends_on:
+    postgres: {condition: service_healthy}
+    redis: {condition: service_healthy}
+  healthcheck:
+    test: ["CMD-SHELL", "curl -sf http://localhost:8080/login/ >/dev/null"]
+    interval: 10s
+    timeout: 5s
+    retries: 60
+    start_period: 60s
+
+x-netbox-env: &netbox-env
+  DB_HOST: postgres
+  DB_USER: netbox
+  DB_PASSWORD: netbox
+  REDIS_HOST: redis
+  SECRET_KEY: netssh-test-environment-secret-key-0123456789-abcdefghijklmnopqrstuvwxyz
+  API_TOKEN_PEPPER_1: netssh-test-environment-pepper-0123456789-abcdefghijklmnop
+  SUPERUSER_NAME: admin
+  SUPERUSER_EMAIL: admin@example.com
+  SUPERUSER_PASSWORD: admin
+  SUPERUSER_API_KEY: netsshtest01
+  SUPERUSER_API_TOKEN: 0123456789abcdef0123456789abcdef01234567
+  SKIP_SUPERUSER: "false"
+
+x-target: &target
+  build:
+    context: ..
+    dockerfile: testenv/targets/target.Dockerfile
+  image: netssh-test-target
+  volumes:
+    - ./.keys/authorized_keys:/keys/authorized_keys:ro
+
+services:
+  postgres:
+    image: postgres:18-alpine
+    environment:
+      POSTGRES_USER: netbox
+      POSTGRES_PASSWORD: netbox
+      POSTGRES_DB: netbox
+    volumes:
+      - ./postgres-init.sql:/docker-entrypoint-initdb.d/init.sql:ro
+      - postgres:/var/lib/postgresql
+    networks: [backend]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U netbox"]
+      interval: 5s
+      retries: 30
+
+  redis:
+    image: redis:8-alpine
+    networks: [backend]
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      retries: 30
+
+  netbox-fsn:
+    <<: *netbox
+    hostname: netbox-fsn
+    environment:
+      <<: *netbox-env
+      DB_NAME: netbox_fsn
+      REDIS_DATABASE: "0"
+      REDIS_CACHE_DATABASE: "1"
+    ports: ["127.0.0.1:18000:8080"]
+    networks:
+      backend: {}
+      public: {ipv4_address: 10.231.0.20}
+
+  netbox-lab:
+    <<: *netbox
+    hostname: netbox-lab
+    environment:
+      <<: *netbox-env
+      DB_NAME: netbox_lab
+      REDIS_DATABASE: "2"
+      REDIS_CACHE_DATABASE: "3"
+    ports: ["127.0.0.1:18001:8080"]
+    networks:
+      backend: {}
+      public: {ipv4_address: 10.231.0.21}
+
+  # Jump host: the only way from the client into the prod network.
+  bastion:
+    <<: *target
+    hostname: bastion
+    networks:
+      public: {ipv4_address: 10.231.0.30, aliases: [bastion.hoster.test]}
+      prod: {ipv4_address: 10.231.2.30}
+
+  fsn1-pve1:
+    <<: *target
+    hostname: fsn1-pve1
+    networks:
+      mgmt: {ipv4_address: 10.231.1.11, aliases: [fsn1-pve1.hoster.test]}
+      prod: {ipv4_address: 10.231.2.11}
+  fsn1-pve2:
+    <<: *target
+    hostname: fsn1-pve2
+    networks:
+      mgmt: {ipv4_address: 10.231.1.12, aliases: [fsn1-pve2.hoster.test]}
+      prod: {ipv4_address: 10.231.2.12}
+  fsn1-pve3:
+    <<: *target
+    hostname: fsn1-pve3
+    networks:
+      mgmt: {ipv4_address: 10.231.1.13, aliases: [fsn1-pve3.hoster.test]}
+      prod: {ipv4_address: 10.231.2.13}
+
+  # VMs of cluster pve-fsn1: only in prod, so they need the bastion.
+  web1:
+    <<: *target
+    hostname: web1
+    networks:
+      prod: {ipv4_address: 10.231.2.21}
+  web2:
+    <<: *target
+    hostname: web2
+    networks:
+      prod: {ipv4_address: 10.231.2.22}
+
+  # NetBox instance "lab": a device and a VM named web1 like the fsn VM.
+  lab-db1:
+    <<: *target
+    hostname: lab-db1
+    networks:
+      mgmt: {ipv4_address: 10.231.1.41}
+  lab-web1:
+    <<: *target
+    hostname: lab-web1
+    networks:
+      mgmt: {ipv4_address: 10.231.1.42}
+
+  # Not in NetBox: tested as a static host.
+  legacy-box:
+    <<: *target
+    hostname: legacy-box
+    networks:
+      public: {ipv4_address: 10.231.0.50}
+
+  # In NetBox with an IPv6 primary address only.
+  v6-host:
+    <<: *target
+    hostname: v6-host
+    networks:
+      public: {ipv4_address: 10.231.0.60, ipv6_address: "fd00:30::60"}
+
+  client:
+    build:
+      context: ..
+      dockerfile: testenv/client.Dockerfile
+    image: netssh-test-client
+    hostname: client
+    init: true
+    volumes:
+      - ./.keys:/keys:ro
+      - ./.state:/state
+      - ./tests:/tests:ro
+      - ./.artifacts:/artifacts
+    networks:
+      public: {ipv4_address: 10.231.0.10, ipv6_address: "fd00:30::10"}
+      mgmt: {ipv4_address: 10.231.1.10}
+
+  # Fills both NetBox instances and writes /state/netssh.yaml, then exits.
+  seed:
+    image: netssh-test-client
+    depends_on:
+      client: {condition: service_started}
+      netbox-fsn: {condition: service_healthy}
+      netbox-lab: {condition: service_healthy}
+    volumes:
+      - ./.state:/state
+      - ./seed:/seed:ro
+    networks:
+      public: {}
+    command: ["python3", "/seed/seed.py"]
+    restart: "no"
+
+# Fixed subnets outside Docker's default address pools (172.17-31.x, 192.168.x),
+# so automatically numbered networks of other projects cannot collide.
+networks:
+  backend:
+    ipam:
+      config:
+        - subnet: 10.231.3.0/24
+  public:
+    enable_ipv6: true
+    ipam:
+      config:
+        - subnet: 10.231.0.0/24
+        - subnet: fd00:30::/64
+  mgmt:
+    ipam:
+      config:
+        - subnet: 10.231.1.0/24
+  prod:
+    ipam:
+      config:
+        - subnet: 10.231.2.0/24
+
+volumes:
+  postgres: {}

testenv/down.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Stop the netssh test environment and remove its volumes and state.
+set -euo pipefail
+cd "$(dirname "$0")"
+docker compose -f compose.yaml down -v --remove-orphans
+rm -rf .state

testenv/postgres-init.sql

@@ -0,0 +1,3 @@
+-- One Postgres serves both NetBox instances of the test environment.
+CREATE DATABASE netbox_fsn OWNER netbox;
+CREATE DATABASE netbox_lab OWNER netbox;

testenv/seed/seed.py

@@ -0,0 +1,171 @@
+"""Fill both NetBox instances of the netssh test environment.
+
+Idempotent: objects are looked up before they are created, so running the
+seed again leaves NetBox unchanged. Writes /state/env (tokens) and
+/state/netssh.yaml (base config for the tests).
+"""
+
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+
+FSN = "http://10.231.0.20:8080"
+LAB = "http://10.231.0.21:8080"
+# Superuser v2 token from compose.yaml (SUPERUSER_API_KEY / SUPERUSER_API_TOKEN).
+V2_TOKEN = "nbt_netsshtest01.0123456789abcdef0123456789abcdef01234567"
+STATE = "/state"
+
+
+class NetBox:
+    def __init__(self, url):
+        self.url = url
+
+    def call(self, method, path, body=None):
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(self.url + "/api/" + path, data=data, method=method)
+        req.add_header("Authorization", "Bearer " + V2_TOKEN)
+        req.add_header("Content-Type", "application/json")
+        req.add_header("Accept", "application/json")
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                raw = resp.read()
+                return json.loads(raw) if raw else None
+        except urllib.error.HTTPError as err:
+            sys.exit(f"{method} {path}: HTTP {err.code}: {err.read().decode(errors='replace')}")
+
+    def find(self, path, **filters):
+        query = "&".join(f"{k}={urllib.request.quote(str(v))}" for k, v in filters.items())
+        results = self.call("GET", f"{path}?{query}&limit=2")["results"]
+        return results[0] if results else None
+
+    def ensure(self, path, lookup, body):
+        """Return the object matching lookup, creating it from body if missing."""
+        found = self.find(path, **lookup)
+        if found:
+            return found
+        return self.call("POST", path, body)
+
+    def wait(self):
+        for _ in range(120):
+            try:
+                self.call("GET", "status/")
+                return
+            except SystemExit:
+                pass
+            except (urllib.error.URLError, ConnectionError, TimeoutError):
+                pass
+            time.sleep(5)
+        sys.exit(f"NetBox {self.url} did not become ready")
+
+
+def base(nb, site, cluster_type, cluster):
+    for tag in ("pve", "web", "bastion", "db", "ipv6"):
+        nb.ensure("extras/tags/", {"slug": tag}, {"name": tag, "slug": tag})
+    site = nb.ensure("dcim/sites/", {"slug": site}, {"name": site, "slug": site, "status": "active"})
+    mfr = nb.ensure("dcim/manufacturers/", {"slug": "generic"}, {"name": "Generic", "slug": "generic"})
+    role = nb.ensure("dcim/device-roles/", {"slug": "server"}, {"name": "Server", "slug": "server", "color": "2196f3"})
+    dtype = nb.ensure("dcim/device-types/", {"slug": "generic-server"},
+                      {"manufacturer": mfr["id"], "model": "Generic Server", "slug": "generic-server"})
+    ctype = nb.ensure("virtualization/cluster-types/", {"slug": cluster_type},
+                      {"name": cluster_type, "slug": cluster_type})
+    cluster = nb.ensure("virtualization/clusters/", {"name": cluster},
+                        {"name": cluster, "type": ctype["id"], "status": "active"})
+    return {"site": site["id"], "role": role["id"], "type": dtype["id"], "cluster": cluster["id"]}
+
+
+def device(nb, ids, name, ips, tags=(), cluster=False, comments=""):
+    """ips: list of (interface, address, primary) with primary in (None, 4, 6)."""
+    body = {"name": name, "role": ids["role"], "device_type": ids["type"], "site": ids["site"],
+            "status": "active", "tags": [{"slug": t} for t in tags], "comments": comments}
+    if cluster:
+        body["cluster"] = ids["cluster"]
+    dev = nb.ensure("dcim/devices/", {"name": name}, body)
+    primary = {}
+    for ifname, address, family in ips:
+        iface = nb.ensure("dcim/interfaces/", {"device_id": dev["id"], "name": ifname},
+                          {"device": dev["id"], "name": ifname, "type": "1000base-t"})
+        ip = nb.ensure("ipam/ip-addresses/", {"address": address},
+                       {"address": address, "assigned_object_type": "dcim.interface", "assigned_object_id": iface["id"]})
+        if family:
+            primary[f"primary_ip{family}"] = ip["id"]
+    if primary:
+        nb.call("PATCH", f"dcim/devices/{dev['id']}/", primary)
+
+
+def vm(nb, ids, name, address, tags=()):
+    machine = nb.ensure("virtualization/virtual-machines/", {"name": name},
+                        {"name": name, "cluster": ids["cluster"], "status": "active",
+                         "tags": [{"slug": t} for t in tags]})
+    iface = nb.ensure("virtualization/interfaces/", {"virtual_machine_id": machine["id"], "name": "eth0"},
+                      {"virtual_machine": machine["id"], "name": "eth0"})
+    ip = nb.ensure("ipam/ip-addresses/", {"address": address},
+                   {"address": address, "assigned_object_type": "virtualization.vminterface",
+                    "assigned_object_id": iface["id"]})
+    nb.call("PATCH", f"virtualization/virtual-machines/{machine['id']}/", {"primary_ip4": ip["id"]})
+
+
+def v1_token(nb):
+    """A legacy v1 token for the lab instance, reused from /state/env if present."""
+    env = read_env()
+    if env.get("LAB_TOKEN"):
+        return env["LAB_TOKEN"]
+    user = nb.find("users/users/", username="admin")
+    token = nb.call("POST", "users/tokens/", {"user": user["id"], "version": 1, "description": "netssh v1 test"})
+    plaintext = token.get("token") or token.get("plaintext")
+    if not plaintext:
+        sys.exit(f"v1 token response without plaintext: {token}")
+    return plaintext
+
+
+def read_env():
+    env = {}
+    try:
+        with open(os.path.join(STATE, "env")) as f:
+            for line in f:
+                key, _, value = line.strip().partition("=")
+                env[key] = value
+    except FileNotFoundError:
+        pass
+    return env
+
+
+def main():
+    fsn, lab = NetBox(FSN), NetBox(LAB)
+    fsn.wait()
+    lab.wait()
+
+    ids = base(fsn, "fsn1", "proxmox", "pve-fsn1")
+    for n in (1, 2, 3):
+        device(fsn, ids, f"fsn1-pve{n}.hoster.test",
+               [("eth0", f"10.231.2.1{n}/24", 4), ("mgmt0", f"10.231.1.1{n}/24", None)],
+               tags=("pve",), cluster=True, comments=f"Proxmox node {n}")
+    device(fsn, ids, "bastion.hoster.test", [("eth0", "10.231.0.30/24", 4)], tags=("bastion",))
+    device(fsn, ids, "v6-host", [("eth0", "fd00:30::60/64", 6)], tags=("ipv6",))
+    vm(fsn, ids, "web1", "10.231.2.21/24", tags=("web",))
+    vm(fsn, ids, "web2", "10.231.2.22/24", tags=("web",))
+
+    ids = base(lab, "lab", "kubernetes", "lab-k8s")
+    device(lab, ids, "lab-db1", [("eth0", "10.231.1.41/24", 4)], tags=("db",))
+    vm(lab, ids, "web1", "10.231.1.42/24", tags=("web",))
+
+    lab_token = v1_token(lab)
+    os.makedirs(STATE, exist_ok=True)
+    with open(os.path.join(STATE, "env"), "w") as f:
+        f.write(f"FSN_URL={FSN}\nLAB_URL={LAB}\nFSN_TOKEN={V2_TOKEN}\nLAB_TOKEN={lab_token}\n")
+    with open(os.path.join(STATE, "netssh.yaml"), "w") as f:
+        f.write(f"""netboxes:
+  - name: fsn
+    url: "{FSN}"
+    token: "{V2_TOKEN}"
+  - name: lab
+    url: "{LAB}"
+    token: "{lab_token}"
+""")
+    print("seed: done (fsn: 3 nodes, bastion, v6-host, 2 VMs; lab: lab-db1, web1)")
+
+
+if __name__ == "__main__":
+    main()

testenv/shell.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Interactive shell in the client with a ready netssh config (fresh home).
+set -euo pipefail
+cd "$(dirname "$0")"
+exec docker compose -f compose.yaml exec -it client bash -c '
+  . /tests/lib.sh
+  new_home
+  base_config >"$XDG_CONFIG_HOME/netssh.yaml" <<EOF
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+ssh:
+  default_user: ops
+  host_key_checking: accept-new
+  rules:
+    - match: {kind: vm, instance: fsn}
+      proxy_jump: ops@10.231.0.30
+EOF
+  echo "netssh is configured (HOME=$HOME). Try: netssh cache refresh && netssh"
+  exec bash -i'

testenv/targets/entrypoint.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+# Prepares host keys and the test users, starts a small HTTP server for the
+# tunnel tests (reachable only on the target itself), then runs sshd.
+set -eu
+
+[ -f /etc/ssh/ssh_host_ed25519_key ] || ssh-keygen -q -t ed25519 -N '' -f /etc/ssh/ssh_host_ed25519_key
+
+for user in ops admin; do
+  home="/home/$user"
+  mkdir -p "$home/.ssh"
+  cp /keys/authorized_keys "$home/.ssh/authorized_keys"
+  chown -R "$user:$user" "$home/.ssh"
+  chmod 700 "$home/.ssh"
+  chmod 600 "$home/.ssh/authorized_keys"
+done
+
+mkdir -p /srv/www
+echo "hello from $(hostname)" > /srv/www/index.html
+python3 -m http.server 8081 --bind 127.0.0.1 --directory /srv/www >/dev/null 2>&1 &
+
+exec /usr/sbin/sshd -D -e

testenv/targets/sshd_config

@@ -0,0 +1,18 @@
+# Test targets accept the generated test key only. Port 2222 tests ssh.default_port.
+Port 22
+Port 2222
+ListenAddress 0.0.0.0
+ListenAddress ::
+HostKey /etc/ssh/ssh_host_ed25519_key
+PermitRootLogin no
+PasswordAuthentication no
+KbdInteractiveAuthentication no
+PubkeyAuthentication yes
+AuthorizedKeysFile .ssh/authorized_keys
+AllowTcpForwarding yes
+AllowAgentForwarding yes
+GatewayPorts no
+PermitTunnel no
+X11Forwarding no
+PrintMotd no
+Subsystem sftp /usr/lib/ssh/sftp-server

testenv/targets/target.Dockerfile

@@ -0,0 +1,16 @@
+# SSH target for the netssh test environment: every NetBox host, the bastion,
+# and the static host run this image with a different hostname.
+FROM alpine:3.23
+
+# Alpine locks new accounts with "!"; sshd refuses key logins for locked
+# accounts, so the password field is set to "*" (no password, not locked).
+RUN apk add --no-cache openssh-server openssh-sftp-server python3 \
+ && for user in ops admin; do \
+      adduser -D -s /bin/sh "$user" && sed -i "s/^$user:!/$user:*/" /etc/shadow; \
+    done
+
+COPY testenv/targets/sshd_config /etc/ssh/sshd_config
+COPY testenv/targets/entrypoint.sh /entrypoint.sh
+
+EXPOSE 22 2222
+ENTRYPOINT ["/entrypoint.sh"]

testenv/test.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Run the test scripts in the client container. Optional FILTER selects files
+# by substring, e.g. testenv/test.sh tunnel. The client is rebuilt first so the
+# tests always run the current source.
+set -euo pipefail
+cd "$(dirname "$0")"
+compose=(docker compose -f compose.yaml)
+if [ "${NO_BUILD:-}" != 1 ]; then
+  "${compose[@]}" build -q client
+  "${compose[@]}" up -d --wait client
+fi
+exec "${compose[@]}" exec -T client bash /tests/run.sh "${1:-}"

testenv/tests/01-cache.sh

@@ -0,0 +1,19 @@
+# Cache refresh across both NetBox instances, filters, list, search, clear.
+config <<'EOF'
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+EOF
+
+expect_out "refresh both instances" "9 entries written" netssh cache refresh
+expect_out "list shows mgmt address" "fsn/fsn1-pve1.hoster.test  10.231.1.11" netssh cache list
+expect_out "list shows lab VM" "lab/web1                   10.231.1.42  vm" netssh cache list
+expect_out "IPv6-only host" "fsn/v6-host                fd00:30::60" netssh cache list
+expect_out "refresh one instance" "2 entries written" netssh cache refresh --instance lab
+expect_out "refresh by tag" "3 entries written" netssh cache refresh --tag pve
+expect_out "refresh by kind" "3 entries written" netssh cache refresh --kind vm
+expect_eq "search" "fsn/fsn1-pve1.hoster.test
+fsn/fsn1-pve2.hoster.test
+fsn/fsn1-pve3.hoster.test" bash -c 'netssh search fsn1 | sort'
+check "clear" netssh cache clear
+expect_eq "empty after clear" "" bash -c 'netssh search fsn'

testenv/tests/02-connect.sh

@@ -0,0 +1,29 @@
+# Connecting with the resolved address, default user and port, overrides.
+config <<'EOF'
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+ssh:
+  default_user: ops
+EOF
+
+expect_eq "connect via NetBox" "fsn1-pve1" netssh fsn/fsn1-pve1.hoster.test hostname
+expect_eq "unique name without instance" "fsn1-pve2" netssh fsn1-pve2.hoster.test hostname
+expect_eq "default user" "ops" netssh fsn/fsn1-pve1.hoster.test whoami
+expect_eq "user@ wins" "admin" netssh admin@fsn/fsn1-pve1.hoster.test whoami
+expect_eq "-l wins" "admin" netssh -l admin fsn/fsn1-pve1.hoster.test whoami
+expect_eq "remote command with arguments" "a b" netssh fsn/fsn1-pve1.hoster.test echo a b
+expect_eq "dry run" "ssh -l ops 10.231.1.11" netssh --dry-run fsn/fsn1-pve1.hoster.test
+
+config <<'EOF'
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+ssh:
+  default_user: ops
+  default_port: 2222
+EOF
+expect_out "default port" " 2222" netssh fsn/fsn1-pve1.hoster.test 'echo $SSH_CONNECTION'
+expect_out "-p wins over default port" " 22" netssh -p 22 fsn/fsn1-pve1.hoster.test 'echo $SSH_CONNECTION'
+expect_eq "dry run with port" "ssh -p 2222 -l ops 10.231.1.11" netssh --dry-run fsn/fsn1-pve1.hoster.test
+expect_eq "version" "netssh" bash -c 'netssh --version | cut -d" " -f1'

testenv/tests/03-resolver.sh

@@ -0,0 +1,63 @@
+# Every resolver strategy against real NetBox data. cache.ttl 0 makes every
+# connection ask NetBox, so each config change takes effect immediately.
+jump='    - match: {instance: fsn}
+      proxy_jump: ops@10.231.0.30
+    - match: {name: "bastion*"}
+      proxy_jump: none'
+
+config <<EOF
+cache: {ttl: 0}
+resolver: {strategies: [primary_ip]}
+ssh:
+  default_user: ops
+  rules:
+$jump
+EOF
+expect_eq "primary_ip uses prod address via bastion" "ssh -l ops -J ops@10.231.0.30 10.231.2.11" netssh --dry-run fsn/fsn1-pve1.hoster.test
+expect_eq "primary_ip connects through the jump host" "fsn1-pve1" netssh fsn/fsn1-pve1.hoster.test hostname
+expect_eq "bastion rule disables the jump" "ssh -l ops 10.231.0.30" netssh --dry-run fsn/bastion.hoster.test
+expect_eq "IPv6 primary address" "ssh -l ops -J ops@10.231.0.30 fd00:30::60" netssh --dry-run fsn/v6-host
+
+config <<'EOF'
+cache: {ttl: 0}
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+ssh: {default_user: ops}
+EOF
+expect_eq "management_subnet" "ssh -l ops 10.231.1.12" netssh --dry-run fsn/fsn1-pve2.hoster.test
+expect_eq "management_subnet falls back to primary_ip" "ssh -l ops 10.231.2.21" netssh --dry-run fsn/web1
+
+config <<'EOF'
+cache: {ttl: 0}
+resolver:
+  strategies: [interface_name, primary_ip]
+  interface_name: mgmt0
+ssh: {default_user: ops}
+EOF
+expect_eq "interface_name" "ssh -l ops 10.231.1.13" netssh --dry-run fsn/fsn1-pve3.hoster.test
+expect_eq "interface_name connects" "fsn1-pve3" netssh fsn/fsn1-pve3.hoster.test hostname
+expect_eq "interface_name falls back for VMs" "ssh -l ops 10.231.2.22" netssh --dry-run fsn/web2
+
+# eth0 holds the prod address, which sorts after mgmt: catches an ignored filter.
+sed -i 's/interface_name: mgmt0/interface_name: eth0/' "$XDG_CONFIG_HOME/netssh.yaml"
+expect_eq "interface_name picks the named interface" "ssh -l ops 10.231.2.13" netssh --dry-run fsn/fsn1-pve3.hoster.test
+
+config <<'EOF'
+cache: {ttl: 0}
+resolver:
+  strategies: [hostname]
+  hostname_domain: example.org
+ssh: {default_user: ops}
+EOF
+expect_eq "hostname strategy" "ssh -l ops fsn1-pve1.hoster.test" netssh --dry-run fsn/fsn1-pve1.hoster.test
+expect_eq "hostname connects via DNS" "fsn1-pve1" netssh fsn/fsn1-pve1.hoster.test hostname
+expect_eq "hostname domain for names without a dot" "ssh -l ops lab-db1.example.org" netssh --dry-run lab/lab-db1
+
+config <<'EOF'
+cache: {ttl: 0}
+resolver:
+  strategies: [interface_name]
+  interface_name: mgmt0
+EOF
+expect_fail "no strategy finds an address" "no strategy resolved an IP" netssh --dry-run fsn/web1

testenv/tests/04-instances.sh

@@ -0,0 +1,20 @@
+# Two NetBox instances: qualified names, ambiguity, an unreachable instance.
+config <<'EOF'
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+ssh:
+  default_user: ops
+  rules:
+    - match: {kind: vm, instance: fsn}
+      proxy_jump: ops@10.231.0.30
+EOF
+expect_fail "same name in both instances is ambiguous" "found 2 exact matches" netssh --dry-run web1
+expect_eq "fsn/web1 through the bastion" "web1" netssh fsn/web1 hostname
+expect_eq "lab/web1 directly" "lab-web1" netssh lab/web1 hostname
+expect_eq "lab uses its v1 token" "lab-db1" netssh lab/lab-db1 hostname
+
+# lab unreachable: qualified fsn targets still work, unqualified ones need every instance.
+sed -i 's#http://10.231.0.21:8080#http://10.231.0.21:9#' "$XDG_CONFIG_HOME/netssh.yaml"
+expect_eq "qualified target with another instance down" "fsn1-pve1" netssh fsn/fsn1-pve1.hoster.test hostname
+expect_fail "unqualified target needs every instance" "10.231.0.21:9" netssh --dry-run fsn1-pve1.hoster.test

testenv/tests/05-shortcuts.sh

@@ -0,0 +1,31 @@
+# Domains, hyphen folding, rewrite rules, alias --test, completion, aliases.
+config <<'EOF'
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+ssh: {default_user: ops}
+shortcuts:
+  domains: [.hoster.test]
+  rewrites:
+    - pattern: '^([a-z]+)[0-9]+-'
+      replace: '$1'
+EOF
+check "refresh" netssh cache refresh
+expect_eq "domain expansion via NetBox" "fsn1-pve1" netssh fsn/fsn1-pve1 hostname
+expect_eq "rewrite shortcut, qualified" "fsn1-pve2" netssh fsn/fsnpve2 hostname
+expect_eq "rewrite shortcut, unqualified" "fsn1-pve3" netssh fsnpve3 hostname
+expect_out "alias --test" "fsn1-pve1.hoster.test → fsnpve1" netssh alias --test fsn1-pve1.hoster.test
+expect_out "completion offers shortcuts" "fsnpve1" netssh __complete fsnp
+expect_out "aliases use the shortcut" "alias fsn_fsnpve1='netssh " netssh alias --shell bash
+expect_fail "unknown shortcut" "host not found" netssh --dry-run fsnpve9
+
+config <<'EOF'
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+shortcuts:
+  domains: [.hoster.test]
+  strip_hyphens: true
+EOF
+check "refresh" netssh cache refresh
+expect_eq "hyphen folding" "ssh 10.231.1.12" netssh --dry-run fsn/fsn1pve2

testenv/tests/06-ssh-options.sh

@@ -0,0 +1,34 @@
+# Jump hosts, rules, host key checking, connection target, options, extra args.
+known="$HOME/known_hosts"
+config <<EOF
+cache: {ttl: 0}
+resolver: {strategies: [primary_ip]}
+ssh:
+  default_user: ops
+  options:
+    UserKnownHostsFile: $known
+    ServerAliveInterval: "30"
+  extra_args: ["-T"]
+  rules:
+    - match: {tag: web}
+      proxy_jump: ops@10.231.0.30
+    - match: {tag: pve}
+      proxy_jump: ops@10.231.0.30
+      host_key_checking: strict
+    - match: {name: "fsn1-pve2*"}
+      host_key_checking: accept-new
+    - match: {name: "fsn1-pve3*"}
+      host_key_checking: "off"
+      target: name
+EOF
+expect_eq "rule by tag adds jump host" "ssh -T -l ops -J ops@10.231.0.30 -o serveraliveinterval=30 -o userknownhostsfile=$known 10.231.2.21" netssh --dry-run fsn/web1
+expect_eq "connect through rule jump" "web1" netssh fsn/web1 hostname
+expect_out "--no-jump removes it" "-o ProxyJump=none" netssh --dry-run --no-jump fsn/web1
+expect_out "--jump overrides it" "-J ops@10.231.0.30" netssh --dry-run --jump ops@10.231.0.30 fsn/v6-host
+expect_fail "strict rejects an unknown host key" "Host key verification failed" netssh fsn/fsn1-pve1.hoster.test hostname
+expect_eq "later rule accept-new wins" "fsn1-pve2" netssh fsn/fsn1-pve2.hoster.test hostname
+expect_out "accept-new stored the key" "10.231.2.12" cat "$known"
+expect_out "off prints a notice" "host key checking is disabled" netssh fsn/fsn1-pve3.hoster.test hostname
+expect_out "target name keeps the address" "-o HostName=10.231.2.13 -o HostKeyAlias=fsn1-pve3.hoster.test" netssh --dry-run fsn/fsn1-pve3.hoster.test
+expect_out "target name destination" " fsn1-pve3.hoster.test" netssh --dry-run fsn/fsn1-pve3.hoster.test
+expect_out "user -o wins over config" "-o ServerAliveInterval=5" netssh --dry-run -o ServerAliveInterval=5 fsn/web1

testenv/tests/07-static.sh

@@ -0,0 +1,25 @@
+# Static hosts without any NetBox: config, CLI, own user/port/options, rules.
+config_only <<'EOF'
+ssh:
+  default_user: ops
+  rules:
+    - match: {kind: static, tag: legacy}
+      options: {ServerAliveInterval: "15"}
+hosts:
+  - name: legacy-box
+    address: 10.231.0.50
+    user: admin
+    tags: [legacy]
+EOF
+expect_eq "connect to a static host" "legacy-box" netssh legacy-box hostname
+expect_eq "static user" "admin" netssh legacy-box whoami
+expect_out "rule by kind and tag" "-o serveraliveinterval=15" netssh --dry-run legacy-box
+expect_eq "-l still wins" "ops" netssh -l ops legacy-box whoami
+check "hosts add" netssh hosts add box2 10.231.0.50 --port 2222 --tag lab
+expect_eq "hosts list" "box2 10.231.0.50 2222 lab" bash -c 'netssh hosts list | grep "^box2" | tr -s " "' 
+expect_out "static port" " 2222" netssh box2 'echo $SSH_CONNECTION'
+expect_out "completion" "box2" netssh __complete bo
+expect_fail "duplicate" "already exists" netssh hosts add box2 10.0.0.1
+check "hosts remove" netssh hosts remove box2
+expect_fail "removed host is gone" "no NetBox is configured" netssh --dry-run box2
+expect_eq "sftp to a static host" "Remote working directory: /home/admin" bash -c 'echo pwd | netssh sftp -b - legacy-box | grep Remote'

testenv/tests/08-transfer.sh

@@ -0,0 +1,24 @@
+# sftp and scp: upload, download, jump host, IPv6, errors.
+config <<'EOF'
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+ssh:
+  default_user: ops
+  rules:
+    - match: {kind: vm, instance: fsn}
+      proxy_jump: ops@10.231.0.30
+EOF
+echo "payload $$" >"$HOME/up.txt"
+check "scp upload" netssh scp "$HOME/up.txt" fsn/fsn1-pve1.hoster.test:/tmp/up.txt
+expect_eq "uploaded content" "payload $$" netssh fsn/fsn1-pve1.hoster.test cat /tmp/up.txt
+check "scp download" netssh scp fsn/fsn1-pve1.hoster.test:/tmp/up.txt "$HOME/down.txt"
+expect_eq "downloaded content" "payload $$" cat "$HOME/down.txt"
+check "scp to a VM through the bastion" netssh scp "$HOME/up.txt" fsn/web1:/tmp/up.txt
+expect_eq "VM content" "payload $$" netssh fsn/web1 cat /tmp/up.txt
+check "scp to IPv6 host" netssh scp "$HOME/up.txt" fsn/v6-host:/tmp/v6.txt
+expect_eq "IPv6 content" "payload $$" netssh fsn/v6-host cat /tmp/v6.txt
+expect_out "sftp starts in the path" "Remote working directory: /tmp" bash -c 'echo pwd | netssh sftp -b - fsn/fsn1-pve2.hoster.test:/tmp'
+expect_out "sftp to IPv6 host" "v6.txt" bash -c 'echo "ls /tmp" | netssh sftp -b - fsn/v6-host'
+expect_out "sftp through the bastion" "up.txt" bash -c 'echo "ls /tmp" | netssh sftp -b - fsn/web1'
+expect_fail "two remote hosts" "not supported" netssh scp fsn/web1:/a fsn/web2:/b

testenv/tests/09-tunnel.sh

@@ -0,0 +1,40 @@
+# Port forwards: named, ad hoc, --forward with a shell, port in use.
+config <<'EOF'
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+ssh:
+  default_user: ops
+  forwards:
+    web: {local: "18081:127.0.0.1:8081"}
+  rules:
+    - match: {kind: vm, instance: fsn}
+      proxy_jump: ops@10.231.0.30
+EOF
+tunnel_test() { # NAME PORT WANT ARGS...
+  local name=$1 port=$2 want=$3 pid out
+  shift 3
+  "$@" >"$HOME/tunnel.log" 2>&1 &
+  pid=$!
+  if wait_for 15 curl -sf "http://127.0.0.1:$port/"; then
+    out=$(curl -s "http://127.0.0.1:$port/")
+    [[ $out == *"$want"* ]] && ok "$name" || bad "$name" "curl: $out"
+  else
+    bad "$name" "tunnel did not open: $(cat "$HOME/tunnel.log")"
+  fi
+  kill "$pid" 2>/dev/null
+  wait "$pid" 2>/dev/null
+}
+tunnel_test "named forward" 18081 "hello from fsn1-pve1" netssh tunnel fsn/fsn1-pve1.hoster.test web
+expect_out "tunnel notice" "forwarding -L 18081:127.0.0.1:8081 via fsn1-pve1.hoster.test" cat "$HOME/tunnel.log"
+tunnel_test "ad hoc spec through the bastion" 18082 "hello from web1" netssh tunnel fsn/web1 18082:127.0.0.1:8081
+tunnel_test "--forward with a remote command" 18081 "hello from fsn1-pve2" netssh --forward web fsn/fsn1-pve2.hoster.test sleep 30
+
+netssh tunnel fsn/fsn1-pve1.hoster.test web >/dev/null 2>&1 &
+holder=$!
+wait_for 15 curl -sf http://127.0.0.1:18081/
+expect_fail "port in use fails instead of hanging" "Address in use" timeout 20 netssh tunnel fsn/fsn1-pve2.hoster.test web
+kill "$holder"; wait "$holder" 2>/dev/null
+
+expect_fail "unknown forward lists the configured ones" "available: web" netssh tunnel fsn/fsn1-pve1.hoster.test db
+expect_fail "tunnel without forward" "forwards for fsn/fsn1-pve1.hoster.test: web" netssh tunnel fsn/fsn1-pve1.hoster.test

testenv/tests/10-notes.sh

@@ -0,0 +1,22 @@
+# Local notes and NetBox comments (v2 token on fsn, v1 token on lab).
+config <<'EOF'
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+EOF
+check "refresh" netssh cache refresh
+host=fsn/fsn1-pve1.hoster.test
+check "set local note" netssh notes set $host "first line"
+check "append local note" netssh notes append $host "second line"
+expect_eq "show local note" "first line
+second line" netssh notes show $host
+expect_eq "note from stdin" "piped" bash -c "echo piped | netssh notes set $host && netssh notes show $host"
+
+expect_eq "read NetBox comments (v2 token)" "Proxmox node 1" netssh notes show $host --netbox
+check "append NetBox comments" netssh notes append $host --netbox "checked by netssh test"
+expect_out "NetBox has the new line" "checked by netssh test" curl -s -H "Authorization: Bearer $FSN_TOKEN" "$FSN_URL/api/dcim/devices/?name=fsn1-pve1.hoster.test"
+check "restore NetBox comments" netssh notes set $host --netbox "Proxmox node 1"
+
+check "set NetBox comments (v1 token)" netssh notes set lab/lab-db1 --netbox "lab note"
+expect_eq "read them back" "lab note" netssh notes show lab/lab-db1 --netbox
+check "clear them" netssh notes set lab/lab-db1 --netbox ""

testenv/tests/11-shell.sh

@@ -0,0 +1,32 @@
+# Completion, aliases, hook install for bash, zsh, fish, and the command alias.
+config <<'EOF'
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+ssh:
+  default_user: ops
+  forwards:
+    web: {local: "18081:127.0.0.1:8081"}
+shortcuts:
+  domains: [.hoster.test]
+shell:
+  alias: j
+EOF
+check "refresh" netssh cache refresh
+expect_out "complete hosts" "fsn/fsn1-pve2.hoster.test" netssh __complete fsn/fsn1
+expect_out "complete scp host:" "fsn/fsn1-pve1.hoster.test:" netssh __complete scp a.txt fsn/fsn1-pve1
+expect_out "complete forwards after the host" "web" netssh __complete tunnel fsn/fsn1-pve1.hoster.test ""
+expect_out "complete --forward" "web" netssh __complete --forward ""
+expect_out "fish aliases" "alias fsn_fsn1-pve1 " netssh alias --shell fish
+
+check "hook install bash" netssh hook install --shell bash
+# Interactive bash without a terminal warns about job control on stderr.
+expect_eq "bash loads host aliases" "fsn1-pve1" sh -c "bash -ic 'fsn_fsn1-pve1 hostname' 2>/dev/null </dev/null"
+expect_eq "bash command alias" "fsn1-pve2" sh -c "bash -ic 'j fsn/fsn1-pve2.hoster.test hostname' 2>/dev/null </dev/null"
+check "hook install zsh" netssh hook install --shell zsh
+expect_eq "zsh loads host aliases" "fsn1-pve3" zsh -ic 'fsn_fsn1-pve3 hostname' </dev/null
+mkdir -p "$XDG_CONFIG_HOME/fish"
+check "hook install fish" netssh hook install --shell fish
+expect_eq "fish loads host aliases" "fsn1-pve1" fish -c 'fsn_fsn1-pve1 hostname' </dev/null
+check "completion install bash" netssh completion install --shell bash
+expect_out "bash completes hosts" "fsn/fsn1-pve2.hoster.test" bash -ic '. ~/.local/share/bash-completion/completions/netssh; COMP_WORDS=(netssh fsn/fsn1-pve2); COMP_CWORD=1; COMP_LINE="netssh fsn/fsn1-pve2"; COMP_POINT=${#COMP_LINE}; __start_netssh netssh; printf "%s\n" "${COMPREPLY[@]}"' </dev/null

testenv/tests/12-tui.sh

@@ -0,0 +1,64 @@
+# The interactive TUI, driven through tmux: search, connect, sftp, tunnel, edit.
+config <<'EOF'
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+ssh:
+  default_user: ops
+  forwards:
+    web: {local: "18085:127.0.0.1:8081"}
+EOF
+check "refresh" netssh cache refresh
+export TMUX_TMPDIR="$HOME/tmux"
+mkdir -p "$TMUX_TMPDIR"
+
+screen() { tmux capture-pane -p -t tui; }
+shows() { screen | grep -qF -- "$1"; }
+tui() { # start netssh in a fresh tmux session
+  tmux kill-server 2>/dev/null
+  tmux new-session -d -s tui -x 160 -y 40 -e HOME="$HOME" -e XDG_CONFIG_HOME="$XDG_CONFIG_HOME" -e XDG_CACHE_HOME="$XDG_CACHE_HOME" netssh
+  wait_for 10 shows "Search hostname"
+}
+step() { # NAME TEXT — wait until the pane shows TEXT
+  if wait_for 15 shows "$2"; then ok "$1"; else bad "$1" "$(screen)"; fi
+}
+
+tui && ok "TUI starts" || bad "TUI starts" "$(screen)"
+tmux send-keys -t tui "fsn1-pve2"
+step "search shows the host" "fsn/fsn1-pve2.hoster.test"
+tmux send-keys -t tui Enter
+sleep 1
+tmux send-keys -t tui "hostname" Enter
+step "enter connects" "fsn1-pve2"
+tmux send-keys -t tui "exit" Enter
+
+tui
+tmux send-keys -t tui "fsn1-pve3"
+wait_for 10 shows "fsn/fsn1-pve3.hoster.test"
+tmux send-keys -t tui C-o
+step "ctrl+o opens sftp" "sftp>"
+tmux send-keys -t tui "pwd" Enter
+step "sftp works" "Remote working directory: /home/ops"
+tmux send-keys -t tui "bye" Enter
+
+tui
+tmux send-keys -t tui "fsn1-pve1"
+wait_for 10 shows "fsn/fsn1-pve1.hoster.test"
+tmux send-keys -t tui C-t
+step "ctrl+t lists configured forwards" "forwards: web"
+tmux send-keys -t tui "web" Enter
+step "tunnel notice" "forwarding -L 18085:127.0.0.1:8081"
+expect_out "tunnel from the TUI works" "hello from fsn1-pve1" curl -s --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:18085/
+tmux send-keys -t tui C-c
+
+tui
+tmux send-keys -t tui "fsn1-pve1"
+wait_for 10 shows "fsn/fsn1-pve1.hoster.test"
+tmux send-keys -t tui C-e
+step "ctrl+e opens the editor" "Connect as: ops@fsn/fsn1-pve1.hoster.test:22"
+tmux send-keys -t tui C-u "admin@fsn/fsn1-pve1.hoster.test:22" Enter
+sleep 1
+tmux send-keys -t tui "whoami" Enter
+step "edited user is used" "admin"
+tmux send-keys -t tui "exit" Enter
+tmux kill-server 2>/dev/null

testenv/tests/13-configure.sh

@@ -0,0 +1,9 @@
+# The configurator in huh's accessible mode: without NetBox, add a static host,
+# save, then connect. Menu numbers follow the order in internal/setup.
+config_only </dev/null
+rm -f "$XDG_CONFIG_HOME/netssh.yaml"
+#                          no NetBox, static hosts, add, name, address, user, port, tags, back, save
+out=$(python3 /tests/drive.py 2 4 1 legacy-box 10.231.0.50 admin "" legacy 5 9)
+[[ $out == *"Config saved"* ]] && ok "configure saves" || bad "configure saves" "$out"
+expect_out "config has the host" 'address: "10.231.0.50"' cat "$XDG_CONFIG_HOME/netssh.yaml"
+expect_eq "connect to the configured host" "admin" netssh legacy-box whoami

testenv/tests/14-uninstall.sh

@@ -0,0 +1,12 @@
+# Uninstall in dry-run mode lists everything netssh created.
+config <<'EOF'
+resolver: {strategies: [primary_ip]}
+EOF
+check "refresh" netssh cache refresh
+check "hook install" netssh hook install --shell bash
+expect_out "lists the profile" ".bashrc" netssh uninstall --dry-run
+expect_out "lists the config" "netssh.yaml" netssh uninstall --dry-run
+expect_out "lists the cache" ".cache/netssh" netssh uninstall --dry-run
+out=$(netssh uninstall --dry-run --keep-config 2>&1)
+[[ $out != *"netssh.yaml"* ]] && ok "--keep-config keeps the config" || bad "--keep-config keeps the config" "$out"
+expect_out "nothing was removed" "netssh shell-init" cat "$HOME/.bashrc"

testenv/tests/15-multi.sh

@@ -0,0 +1,74 @@
+# netssh multi with real tmux and zellij: selectors against NetBox, panes,
+# broadcast typing reaching every host, netssh sync, zellij layouts and tabs.
+config <<'EOF'
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+ssh:
+  default_user: ops
+  rules:
+    - match: {kind: vm, instance: fsn}
+      proxy_jump: ops@10.231.0.30
+groups:
+  pve: ["cluster:pve-fsn1"]
+  mixed: ["@pve", "lab/lab-db1", "tag:web"]
+EOF
+check "refresh" netssh cache refresh
+nodes="fsn/fsn1-pve1.hoster.test fsn/fsn1-pve2.hoster.test fsn/fsn1-pve3.hoster.test"
+expect_out "cluster: selects the devices" "# 3 hosts: $nodes" netssh multi --dry-run --tmux cluster:pve-fsn1
+expect_out "--kind vm selects the VMs" "# 2 hosts: fsn/web1 fsn/web2" netssh multi --dry-run --tmux --kind vm cluster:pve-fsn1
+expect_out "groups, tags, and hosts combined" "# 7 hosts: $nodes lab/lab-db1 fsn/web1 fsn/web2 lab/web1" netssh multi --dry-run --tmux @mixed
+expect_fail "unknown cluster" "matches no hosts" netssh multi --dry-run --tmux cluster:nope
+expect_out "completion offers clusters" "cluster:pve-fsn1" netssh __complete multi cluster:
+expect_out "completion offers groups" "@pve" netssh __complete multi @
+
+export TMUX_TMPDIR="$HOME/tmux"
+mkdir -p "$TMUX_TMPDIR" "$HOME/.config/zellij"
+# No first-start tips or release notes on top of the panes.
+printf 'show_startup_tips false\nshow_release_notes false\n' >"$HOME/.config/zellij/config.kdl"
+envs=(-e HOME="$HOME" -e XDG_CONFIG_HOME="$XDG_CONFIG_HOME" -e XDG_CACHE_HOME="$XDG_CACHE_HOME")
+hosts_of() { tmux list-panes -t "$1" -F '#{@netssh_host}' 2>/dev/null | sort | tr '\n' ' '; }
+# wait_for retries a command, so checks must re-evaluate on every call.
+panes_in() { [ "$(tmux list-panes -t "$1" 2>/dev/null | wc -l)" = "$2" ]; }
+sync_is() { [ "$(tmux show-window-options -t "$1" -v synchronize-panes 2>/dev/null)" = "$2" ]; }
+prompts() { [ "$(tmux capture-pane -p -t z | grep -o 'fsn1-pve[123]:~\$' | sort -u | wc -l)" = 3 ]; }
+remote_file() { for n in 1 2 3; do netssh "fsn/fsn1-pve$n.hoster.test" test -f "$1" || return 1; done; }
+
+# Inside tmux: a new window in the current session, broadcast from the start.
+tmux new-session -d -s outer -x 200 -y 60 "${envs[@]}" bash
+tmux send-keys -t outer "netssh multi --sync @pve" Enter
+if wait_for 20 panes_in outer:pve 3; then ok "tmux: three panes in a new window"; else bad "tmux: three panes in a new window" "$(tmux list-windows -a)"; fi
+expect_eq "tmux: panes are labelled" "$nodes " hosts_of outer:pve
+expect_eq "tmux: broadcast is on" "on" tmux show-window-options -t outer:pve -v synchronize-panes
+sleep 2
+marker="/tmp/netssh-multi-$$"
+tmux send-keys -t outer:pve "touch $marker" Enter
+if wait_for 15 remote_file "$marker"; then ok "tmux: one command reached all three hosts"; else bad "tmux: one command reached all three hosts" "$(tmux capture-pane -p -t outer:pve)"; fi
+
+tmux new-window -t outer -n ctl "${envs[@]}" bash
+tmux send-keys -t outer:ctl "netssh sync" Enter
+if wait_for 10 sync_is outer:ctl on; then ok "netssh sync toggles broadcast"; else bad "netssh sync toggles broadcast" "$(tmux capture-pane -p -t outer:ctl)"; fi
+
+# Outside tmux: a new session, attached.
+tmux send-keys -t outer:ctl "netssh sync; env -u TMUX netssh multi --kind vm cluster:pve-fsn1" Enter
+if wait_for 20 panes_in netssh-pve-fsn1 2; then ok "tmux: new session outside tmux"; else bad "tmux: new session outside tmux" "$(tmux list-sessions)"; fi
+expect_eq "tmux: VMs through the bastion" "fsn/web1 fsn/web2 " hosts_of netssh-pve-fsn1
+tmux kill-server
+
+# zellij outside a session: netssh starts zellij with a grid layout.
+tmux new-session -d -s z -x 200 -y 60 "${envs[@]}" bash
+tmux send-keys -t z "netssh multi --zellij @pve" Enter
+zscreen() { tmux capture-pane -p -t z; }
+if wait_for 30 prompts; then ok "zellij: three panes with remote shells"; else bad "zellij: three panes with remote shells" "$(zscreen)"; fi
+expect_out "zellij: pane titles" "fsn/fsn1-pve2.hoster.test" zscreen
+zsession() { zellij list-sessions --short --no-formatting 2>/dev/null | head -1 | grep .; }
+if wait_for 10 zsession; then ok "zellij: session is running"; else bad "zellij: session is running" "$(zellij list-sessions 2>&1)"; fi
+session=$(zsession)
+
+# zellij inside that session: netssh multi adds a tab.
+ZELLIJ_SESSION_NAME=$session ZELLIJ=0 netssh multi --kind vm cluster:pve-fsn1 >/dev/null 2>&1
+expect_out "zellij: new tab inside a session" "pve-fsn1" zellij --session "$session" action query-tab-names
+expect_out "zellij: tab layout runs netssh for the VMs" "fsn/web2" zellij --session "$session" action dump-layout
+zellij kill-all-sessions --yes >/dev/null 2>&1
+tmux kill-server 2>/dev/null
+true

testenv/tests/16-render.sh

@@ -0,0 +1,102 @@
+# What a user sees: tmux, zellij, and the TUI rendered by a real terminal
+# emulator (xterm on Xvfb), checked by OCR of screenshots. The screenshots stay
+# in testenv/.artifacts/ for a look by eye.
+config <<'EOF'
+resolver:
+  strategies: [management_subnet, primary_ip]
+  management_subnets: [10.231.1.0/24]
+ssh: {default_user: ops}
+groups:
+  pve: ["cluster:pve-fsn1"]
+EOF
+check "refresh" netssh cache refresh
+export TMUX_TMPDIR="$HOME/tmux"
+mkdir -p "$TMUX_TMPDIR" "$HOME/.config/zellij"
+printf 'show_startup_tips false\nshow_release_notes false\n' >"$HOME/.config/zellij/config.kdl"
+start_screen && ok "X server and xterm" || bad "X server and xterm" "Xvfb did not start"
+
+p1=fsn/fsn1-pve1.hoster.test p2=fsn/fsn1-pve2.hoster.test p3=fsn/fsn1-pve3.hoster.test
+prompts() { screen_shows "$1" "fsn1-pve1:~\$" "fsn1-pve2:~\$" "fsn1-pve3:~\$"; }
+# Two hosts on one OCR line means their panes sit side by side (tiled grid).
+side_by_side() { screen_text "$1" | ocr_norm | grep -F "$(printf %s "$2" | ocr_norm)" | grep -qF "$(printf %s "$3" | ocr_norm)"; }
+visible() { # NAME SHOT TEXT... — wait until the screen shows every TEXT
+  local name=$1 shot=$2
+  shift 2
+  if wait_for 30 screen_shows "$shot" "$@"; then ok "$name"; else bad "$name" "$(screen_text "$shot")"; fi
+}
+
+# --- tmux, started from a plain terminal: new session, attached in xterm ---
+term netssh multi --sync @pve
+visible "tmux: three remote shells on screen" tmux-1 "fsn1-pve1:~\$" "fsn1-pve2:~\$" "fsn1-pve3:~\$"
+visible "tmux: borders show host and [SYNC]" tmux-1 "$p1 [SYNC]" "$p2 [SYNC]" "$p3 [SYNC]"
+side_by_side tmux-1 "$p1" "$p2" && ok "tmux: tiled, first two panes side by side" || bad "tmux: tiled, first two panes side by side" "$(screen_text tmux-1)"
+tmux send-keys -t netssh-pve "echo typed-once-\$(hostname)" Enter
+visible "tmux: broadcast output in every pane" tmux-2 "typed-once-fsn1-pve1" "typed-once-fsn1-pve2" "typed-once-fsn1-pve3"
+# Keys as typed in xterm (send-keys -K goes through the client's prefix and
+# key tables): prefix e excludes the active pane, prefix S toggles all panes.
+client=$(tmux list-clients -t netssh-pve -F '#{client_name}' | head -1)
+press() { tmux send-keys -K -c "$client" C-b "$1"; sleep 0.5; }
+panes=($(tmux list-panes -t netssh-pve -F '#{pane_id}'))
+tmux select-pane -t "${panes[2]}"
+press e
+visible "tmux: prefix e marks the pane [SOLO]" tmux-solo "$p3 [SOLO]" "$p1 [SYNC]" "$p2 [SYNC]"
+tmux send-keys -t "${panes[2]}" "echo solo-only" Enter
+tmux send-keys -t "${panes[0]}" "echo two-panes" Enter
+sleep 1
+shot tmux-solo-2
+[ "$(screen_count tmux-solo-2 "solo-only")" = 2 ] && ok "tmux: the excluded pane types alone" || bad "tmux: the excluded pane types alone" "$(screen_text tmux-solo-2)"
+[ "$(screen_count tmux-solo-2 "two-panes")" = 4 ] && ok "tmux: broadcast skips the excluded pane" || bad "tmux: broadcast skips the excluded pane" "$(screen_text tmux-solo-2)"
+press e
+visible "tmux: prefix e again includes it" tmux-solo-3 "$p3 [SYNC]"
+
+press S
+sync_is() { [ "$(tmux show-window-options -t netssh-pve -v synchronize-panes 2>/dev/null)" = "$1" ]; }
+wait_for 5 sync_is off && ok "tmux: prefix S turns broadcast off" || bad "tmux: prefix S turns broadcast off" "$(tmux show-window-options -t netssh-pve)"
+tmux send-keys -t netssh-pve "echo just-this-pane" Enter
+sleep 1
+shot tmux-3
+[ "$(screen_count tmux-3 "just-this-pane")" = 2 ] && ok "tmux: without broadcast only one pane gets input" || bad "tmux: without broadcast only one pane gets input" "$(screen_text tmux-3)"
+shows_sync() { screen_shows tmux-3 "[SYNC]"; }
+shows_sync && bad "tmux: [SYNC] disappears when broadcast is off" "$(screen_text tmux-3)" || ok "tmux: [SYNC] disappears when broadcast is off"
+press S
+wait_for 5 sync_is on && ok "tmux: prefix S turns it on again" || bad "tmux: prefix S turns it on again" "$(tmux show-window-options -t netssh-pve)"
+tmux kill-server
+
+# --- more hosts than panes_per_window: further windows ---
+sed -i 's/^groups:/multi: {panes_per_window: 2}\ngroups:/' "$XDG_CONFIG_HOME/netssh.yaml"
+term netssh multi @pve
+visible "tmux: hosts split over windows pve-1 and pve-2" tmux-windows "pve-1" "pve-2"
+visible "tmux: status bar shows the whole session name" tmux-windows "[netssh-pve]"
+tmux kill-server
+sed -i '/^multi: {panes_per_window: 2}$/d' "$XDG_CONFIG_HOME/netssh.yaml"
+
+# --- zellij: generated grid layout, broadcast through the sync tab ---
+term netssh multi --zellij @pve
+visible "zellij: three remote shells on screen" zellij-1 "fsn1-pve1:~\$" "fsn1-pve2:~\$" "fsn1-pve3:~\$"
+visible "zellij: pane titles show the hosts" zellij-1 "$p1" "$p2" "$p3"
+side_by_side zellij-1 "$p1" "$p2" && ok "zellij: grid, first two panes side by side" || bad "zellij: grid, first two panes side by side" "$(screen_text zellij-1)"
+session=$(zellij list-sessions --short --no-formatting 2>/dev/null | head -1)
+zellij --session "$session" action toggle-active-sync-tab
+zellij --session "$session" action write-chars 'echo zellij-$(hostname)'
+zellij --session "$session" action write 13
+visible "zellij: broadcast output in every pane" zellij-2 "zellij-fsn1-pve1" "zellij-fsn1-pve2" "zellij-fsn1-pve3"
+zellij kill-all-sessions --yes >/dev/null 2>&1
+
+# --- TUI: mark hosts, open them together ---
+term tmux new-session -s tui netssh
+visible "TUI: search screen" tui-1 "Search hostname"
+# The netssh keys do nothing outside netssh multi windows.
+tmux source-file "$XDG_CACHE_HOME/netssh/netssh-multi.tmux.conf"
+client=$(tmux list-clients -t tui -F '#{client_name}' | head -1)
+tmux send-keys -K -c "$client" C-b S
+sleep 0.5
+[ "$(tmux show-window-options -t tui -v synchronize-panes 2>/dev/null)" != on ] && ok "tmux: prefix S leaves other windows alone" || bad "tmux: prefix S leaves other windows alone" "synchronize-panes turned on in a non-netssh window"
+tmux send-keys -t tui "pve"
+visible "TUI: results listed" tui-2 "$p1" "$p2" "$p3"
+tmux send-keys -t tui C-a
+visible "TUI: all marked" tui-3 "3 marked"
+tmux send-keys -t tui Enter
+visible "TUI: marked hosts open side by side" tui-4 "fsn1-pve1:~\$" "fsn1-pve2:~\$" "fsn1-pve3:~\$"
+tmux kill-server
+
+stop_screen

testenv/tests/drive.py

@@ -0,0 +1,32 @@
+"""Drive `netssh configure` in huh's accessible mode (TERM=dumb): one answer
+per prompt, sent after a short pause so each form reads its own line."""
+import os
+import pty
+import select
+import sys
+import time
+
+answers = sys.argv[1:]
+pid, fd = pty.fork()
+if pid == 0:
+    os.execvpe("netssh", ["netssh", "configure"], dict(os.environ, TERM="dumb"))
+out = b""
+
+
+def drain(seconds):
+    global out
+    end = time.time() + seconds
+    while time.time() < end:
+        ready, _, _ = select.select([fd], [], [], 0.05)
+        if ready:
+            try:
+                out += os.read(fd, 4096)
+            except OSError:
+                return
+
+
+for answer in answers:
+    drain(0.5)
+    os.write(fd, (answer + "\n").encode())
+drain(2)
+sys.stdout.write(out.decode(errors="replace"))

testenv/tests/lib.sh

@@ -0,0 +1,154 @@
+# Helpers for the netssh test environment. Sourced by run.sh, the tests, and
+# shell.sh inside the client container.
+
+# shellcheck disable=SC1091
+. /state/env
+RESULTS=${RESULTS:-/tmp/netssh-results}
+
+# new_home gives each test file its own netssh config, cache, notes, and rc files.
+new_home() {
+  HOME=$(mktemp -d /tmp/home.XXXXXX)
+  export HOME XDG_CONFIG_HOME="$HOME/.config" XDG_CACHE_HOME="$HOME/.cache" SHELL=/bin/bash
+  mkdir -p "$XDG_CONFIG_HOME" "$XDG_CACHE_HOME"
+  unset TMUX ZELLIJ NETSSH_NETBOX_URL NETSSH_NETBOX_TOKEN
+  cd "$HOME" || exit 1
+}
+
+# base_config prints both NetBox instances followed by stdin.
+base_config() { cat /state/netssh.yaml -; }
+
+# config writes the netssh config: both NetBox instances plus stdin.
+config() { base_config >"$XDG_CONFIG_HOME/netssh.yaml"; }
+
+# config_only writes stdin as the whole config (no NetBox).
+config_only() { cat >"$XDG_CONFIG_HOME/netssh.yaml"; }
+
+ok() {
+  echo "ok $CURRENT: $1" >>"$RESULTS"
+  printf '  \033[32mok\033[0m    %s\n' "$1"
+}
+bad() {
+  echo "FAIL $CURRENT: $1" >>"$RESULTS"
+  printf '  \033[31mFAIL\033[0m  %s\n' "$1"
+  printf '%s\n' "$2" | sed 's/^/        /'
+}
+
+# check NAME CMD... — CMD must succeed.
+check() {
+  local name=$1 out
+  shift
+  if out=$("$@" 2>&1); then ok "$name"; else bad "$name" "exit $?: $out"; fi
+}
+
+# expect_out NAME WANT CMD... — CMD must succeed and print WANT (substring).
+expect_out() {
+  local name=$1 want=$2 out rc
+  shift 2
+  out=$("$@" 2>&1) && rc=0 || rc=$?
+  if [ "$rc" = 0 ] && [[ $out == *"$want"* ]]; then ok "$name"; else bad "$name" "want: $want
+got (exit $rc): $out"; fi
+}
+
+# expect_eq NAME WANT CMD... — CMD must succeed and print exactly WANT.
+expect_eq() {
+  local name=$1 want=$2 out rc
+  shift 2
+  out=$("$@" 2>&1) && rc=0 || rc=$?
+  if [ "$rc" = 0 ] && [ "$out" = "$want" ]; then ok "$name"; else bad "$name" "want: $want
+got (exit $rc): $out"; fi
+}
+
+# expect_fail NAME WANT CMD... — CMD must fail and print WANT (substring).
+expect_fail() {
+  local name=$1 want=$2 out rc
+  shift 2
+  out=$("$@" 2>&1) && rc=0 || rc=$?
+  if [ "$rc" != 0 ] && [[ $out == *"$want"* ]]; then ok "$name"; else bad "$name" "want failure with: $want
+got (exit $rc): $out"; fi
+}
+
+# wait_for TIMEOUT CMD... — retry CMD every 0.2 s until it succeeds.
+wait_for() {
+  local deadline=$((SECONDS + $1))
+  shift
+  until "$@" >/dev/null 2>&1; do
+    [ $SECONDS -ge $deadline ] && return 1
+    sleep 0.2
+  done
+}
+
+# --- rendering in a real terminal emulator (tests/16-render.sh) ---
+# Xvfb provides a screen, xterm renders the terminal, `import` takes a
+# screenshot, and tesseract reads it back, so checks see what a user sees.
+
+start_screen() {
+  Xvfb :99 -screen 0 1920x1080x24 -nolisten tcp >/dev/null 2>&1 &
+  XVFB_PID=$!
+  export DISPLAY=:99
+  wait_for 10 import -window root -crop 1x1+0+0 null:
+}
+
+stop_screen() {
+  pkill -u "$(id -u)" xterm 2>/dev/null
+  kill "$XVFB_PID" 2>/dev/null
+  wait "$XVFB_PID" 2>/dev/null
+}
+
+# term CMD... — run CMD in a full-screen xterm (UTF-8, DejaVu Sans Mono).
+term() {
+  pkill -u "$(id -u)" xterm 2>/dev/null
+  xterm -u8 -geometry 190x52+0+0 -fa 'DejaVu Sans Mono' -fs 11 -bg '#1e1e1e' -fg '#d4d4d4' \
+    -T netssh -e "$@" >/dev/null 2>&1 &
+  sleep 1
+}
+
+# shot NAME — screenshot to /artifacts/NAME.png.
+shot() { import -window root "/artifacts/$1.png"; }
+
+# OCR preprocessing variants: no single one reads everything (dim hint lines,
+# red/green borders): plain luminance, stretched dark range for dim gray, and
+# the brightest color channel for colored text.
+OCR_VARIANTS=("-colorspace gray" "-colorspace gray -level 10%,40%"
+  "-channel RGB -separate -evaluate-sequence max -level 10%,60%")
+
+# ocr_variant NAME I — OCR of screenshot NAME with preprocessing variant I.
+ocr_variant() {
+  # shellcheck disable=SC2086
+  magick "/artifacts/$1.png" ${OCR_VARIANTS[$2]} -negate -resize 300% png:- |
+    tesseract stdin stdout --psm 6 2>/dev/null
+}
+
+# screen_text NAME — the text of all variants combined.
+screen_text() {
+  local i
+  for i in "${!OCR_VARIANTS[@]}"; do ocr_variant "$1" "$i"; done
+}
+
+# ocr_norm maps characters OCR confuses in DejaVu Sans Mono (1/l/I/|, C/( , 0/O,
+# typographic dashes for "-") to one form; expected text gets the same mapping,
+# so comparisons stay strict about everything else.
+ocr_norm() { sed 's/[‐‑‒–—―−]/-/g' | tr 'lI|(O' '111C0'; }
+
+# screen_shows NAME TEXT... — take a screenshot and check that OCR finds every TEXT.
+screen_shows() {
+  local name=$1 text want
+  shift
+  shot "$name"
+  text=$(screen_text "$name" | ocr_norm)
+  for want in "$@"; do
+    want=$(printf '%s' "$want" | ocr_norm)
+    [[ $text == *"$want"* ]] || return 1
+  done
+}
+
+# screen_count NAME TEXT — how often TEXT is on screenshot NAME: the highest
+# count of any OCR variant (they read the same screen, so they are not added).
+screen_count() {
+  local want i n max=0
+  want=$(printf '%s' "$2" | ocr_norm)
+  for i in "${!OCR_VARIANTS[@]}"; do
+    n=$(ocr_variant "$1" "$i" | ocr_norm | grep -oF -- "$want" | wc -l)
+    [ "$n" -gt "$max" ] && max=$n
+  done
+  echo "$max"
+}

testenv/tests/run.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Runs every tests/NN-*.sh (or those matching $1) in a fresh netssh home and
+# prints a summary. Exit code 1 if any check failed.
+set -u
+export RESULTS=/tmp/netssh-results
+: >"$RESULTS"
+filter=${1:-}
+for file in /tests/[0-9][0-9]-*.sh; do
+  name=$(basename "$file" .sh)
+  [[ -n $filter && $name != *"$filter"* ]] && continue
+  echo "== $name"
+  (
+    export CURRENT=$name
+    . /tests/lib.sh
+    new_home
+    . "$file"
+  )
+done
+passed=$(grep -c '^ok ' "$RESULTS" || true)
+failed=$(grep -c '^FAIL ' "$RESULTS" || true)
+echo
+echo "passed: $passed, failed: $failed"
+if [ "$failed" -gt 0 ]; then
+  grep '^FAIL ' "$RESULTS" | sed 's/^/  /'
+  exit 1
+fi

testenv/up.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Start the netssh test environment: generate the test key, build the images
+# (netssh from the current source), start everything, and seed NetBox.
+set -euo pipefail
+cd "$(dirname "$0")"
+compose=(docker compose -f compose.yaml)
+
+mkdir -p .keys .state .artifacts
+chmod a+rwx .state .artifacts # written by the container user (screenshots in .artifacts)
+if [ ! -f .keys/id_ed25519 ]; then
+  ssh-keygen -q -t ed25519 -N '' -C netssh-test -f .keys/id_ed25519
+  cp .keys/id_ed25519.pub .keys/authorized_keys
+fi
+# Throwaway test key: readable by the container user; tests copy it with 0600.
+chmod 644 .keys/id_ed25519 .keys/authorized_keys
+
+"${compose[@]}" build
+"${compose[@]}" up -d --wait --wait-timeout 600 \
+  postgres redis netbox-fsn netbox-lab bastion fsn1-pve1 fsn1-pve2 fsn1-pve3 \
+  web1 web2 lab-db1 lab-web1 legacy-box v6-host client
+"${compose[@]}" run --rm seed
+echo
+echo "Test environment is up."
+echo "  Tests:        testenv/test.sh [FILTER]"
+echo "  Shell:        testenv/shell.sh"
+echo "  NetBox UI:    http://127.0.0.1:18000 (fsn), http://127.0.0.1:18001 (lab) — admin / admin"