From 792b2baa447a3ed413cc755ea3d76582021c648a Mon Sep 17 00:00:00 2001 From: kangal-bot <285672167+kangal-bot@users.noreply.github.com> Date: Mon, 7 Sep 2026 22:04:42 +0000 Subject: [PATCH] docs: publish preview documentation --- distribution/preview.json | 61 ++++++++--- .../src/content/docs/agent-automation.mdx | 6 +- .../src/content/docs/cli-reference.mdx | 28 +++-- .../website/src/content/docs/concepts.mdx | 2 + .../src/content/docs/configuration.mdx | 23 ++++ .../src/content/docs/connecting-machines.mdx | 100 ++++++++++++++++++ .../website/src/content/docs/how-to-work.mdx | 4 +- .../website/src/content/docs/index.mdx | 5 + .../src/content/docs/ja/agent-automation.mdx | 6 +- .../src/content/docs/ja/cli-reference.mdx | 28 +++-- .../website/src/content/docs/ja/concepts.mdx | 2 + .../src/content/docs/ja/configuration.mdx | 25 ++++- .../content/docs/ja/connecting-machines.mdx | 100 ++++++++++++++++++ .../src/content/docs/ja/how-to-work.mdx | 4 +- .../website/src/content/docs/ja/index.mdx | 5 + .../content/docs/ja/persistence-remote.mdx | 72 ++++++------- .../src/content/docs/ja/socket-api.mdx | 2 +- .../src/content/docs/ja/troubleshooting.mdx | 2 +- .../src/content/docs/persistence-remote.mdx | 45 ++------ .../content/docs/zh-cn/agent-automation.mdx | 6 +- .../src/content/docs/zh-cn/cli-reference.mdx | 28 +++-- .../src/content/docs/zh-cn/concepts.mdx | 2 + .../src/content/docs/zh-cn/configuration.mdx | 25 ++++- .../docs/zh-cn/connecting-machines.mdx | 100 ++++++++++++++++++ .../src/content/docs/zh-cn/how-to-work.mdx | 4 +- .../website/src/content/docs/zh-cn/index.mdx | 5 + .../content/docs/zh-cn/persistence-remote.mdx | 72 ++++++------- .../src/content/docs/zh-cn/socket-api.mdx | 2 +- .../content/docs/zh-cn/troubleshooting.mdx | 2 +- .../website/src/data/config-reference.json | 17 +-- 30 files changed, 595 insertions(+), 188 deletions(-) create mode 100644 docs/preview/website/src/content/docs/connecting-machines.mdx create mode 100644 docs/preview/website/src/content/docs/ja/connecting-machines.mdx create mode 100644 docs/preview/website/src/content/docs/zh-cn/connecting-machines.mdx diff --git a/distribution/preview.json b/distribution/preview.json index 51d3438d..cf16e1dd 100644 --- a/distribution/preview.json +++ b/distribution/preview.json @@ -1,37 +1,68 @@ { "schema_version": 1, "channel": "preview", - "base_version": "0.8.2", - "build_id": "2026-09-06-9e9bc8a14466", - "commit": "9e9bc8a144667a6b7debfd4f0c7a31ff0e11493a", - "built_at": "2026-09-06T10:25:52Z", + "base_version": "0.9.0", + "build_id": "2026-09-08-62431dbd033b", + "commit": "62431dbd033bf1be2fe87fbc526df28084214e49", + "built_at": "2026-09-07T21:49:44Z", "protocol": 22, "endpoint_generation": 1, - "notes": "Preview build 2026-09-06-9e9bc8a14466\n\nBuilt from `9e9bc8a14466` on `master`.\nBase stable: v0.8.2\nCompare: https://github.com/herdrdev/herdr/compare/b1ff4582e9688f52ffb943cfa8bee4871ae122e4...9e9bc8a144667a6b7debfd4f0c7a31ff0e11493a\n\n### Added\n- Manage multiple ssh machines from one client (#3670)\n- Enable kitty graphics by default\n- Support independent multi-client tab views (#3526)\n- Add stable client endpoint compatibility (#3509)\n\n### Fixed\n- Prevent OpenCode child prompts from leaving status blocked (#3669)\n- Resolve Windows plugin pane launch paths (#3666)\n- Run the full applicable test suite on windows (#3660)\n- Keep selections visible without host colors (#2710)\n- Retain mouse selections across unrelated terminal output (#3641)\n- Preserve pixel mouse after sgr reassertion (#3637)\n- Make Windows Codex prompt delay size-aware (#3552)\n- Detect codex startup update prompts (#3636)\n- Use active release directory on PATH (#3618)\n- Persist Codex resume sessions at launch (#3617)\n- Resolve Devin config on Windows (#3595)\n- Statically link the Windows CRT (#3594)\n- Reject Android in Unix installer (#3577)\n- Preserve LF paste order (#3582)\n- Batch host palette updates (#3580)\n- Preserve ctrl+slash key identity (#3578)\n- Read Windows clipboard images in WSL (#3572)\n- Reveal newly focused spaces in the sidebar (#3554)\n- Preserve dead-key composition in kitty panes (#3548)\n- Include short viewport output in recent reads (#3448)\n- Keep direct graphics bound to its client (#3549)\n- Remove worktrees with active agent panes (#3532)\n- Stop treating claude background shells as working (#3468)\n- Preserve mouse selection during pane output (#3538)\n- Detach when terminal geometry is unavailable (#3531)\n- Reliably submit delayed agent prompts (#3506)\n- Keep openssh mouse input draining (#3512)\n- Preserve remote multiline paste (#3282)\n- Preserve native pane key identity (#3503)\n- Guide users when zig is missing (#2281)\n- Recognize durable wmi daemon jobs (#3507)\n- Reject malformed process environments (#3500)\n- Fetch crates from static CDN (#3504)\n- Parse openssh mouse reports with physical escape (#3502)\n- Launch powershell agent shims with arguments (#3455)\n- Enable mouse reporting over openssh (#3461)\n\n### Performance\n- Compress idle terminal scrollback (#3556)\n\n### Maintenance\n- Approve markjaquith as contributor\n- Allow slow documentation snapshot fixtures\n- Render the shell in the client (#3487)\n- Separate website presentation from runtime\n- Trigger private website deploys\n- Publish preview documentation\n- Stabilize headless metadata expiry check (#3453)", + "notes": "Preview build 2026-09-08-62431dbd033b\n\nBuilt from `62431dbd033b` on `master`.\nBase stable: v0.9.0\nCompare: https://github.com/herdrdev/herdr/compare/v0.9.0...62431dbd033bf1be2fe87fbc526df28084214e49\n\n### Fixed\n- Reduce idle ssh cpu without dropping final output (#3728)", "assets": { "linux-x86_64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-06-9e9bc8a14466/herdr-linux-x86_64", - "sha256": "a517cef9f178e7339d855a927ae9f3cc541c7b5d8e757c75b405fdc64a2f79ec" + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-08-62431dbd033b/herdr-linux-x86_64", + "sha256": "3f56cab5d1d27b87f6cd2addfa3809bf48a58b345b13746419d1b8e951e0667d" }, "linux-aarch64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-06-9e9bc8a14466/herdr-linux-aarch64", - "sha256": "390c596e198d5487bce08ee1e411fae0cade80e838312f594e1bcf3377548aa3" + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-08-62431dbd033b/herdr-linux-aarch64", + "sha256": "47f075a0531ab6c36ec8f3144e634ea02c1307a1de405e29db3fd4d80efeb068" }, "macos-x86_64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-06-9e9bc8a14466/herdr-macos-x86_64", - "sha256": "917800c568ef8971c7323cd35453d73cabea60ed5e62f6e3307fbbb2f78cf5d4" + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-08-62431dbd033b/herdr-macos-x86_64", + "sha256": "6b68aaf84ad62198773d9a710dea3d364dbd6c1ff65abdff8eb6e5a71a57830d" }, "macos-aarch64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-06-9e9bc8a14466/herdr-macos-aarch64", - "sha256": "889ccc0ee7d5feb9a74aa38ceb729c57ce0d64415f3b88ac0564523db17d68e0" + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-08-62431dbd033b/herdr-macos-aarch64", + "sha256": "d6b6ad08961e7b491fc19a4cd8570f0231734672cfc4d6c0db6327437ac11065" }, "windows-x86_64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-06-9e9bc8a14466/herdr-windows-x86_64.zip", - "sha256": "991abaf23ef7008a6ef91e6c0dbc6caac7f8bfebe9d14e54294ccc6b5352d99e", + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-08-62431dbd033b/herdr-windows-x86_64.zip", + "sha256": "5904ceb4fdb3aa4c377f88ee8d2676bb39fcf62c6a8f034e6147cf21a98e6cb0", "format": "zip" } }, "builds": { + "2026-09-08-62431dbd033b": { + "base_version": "0.9.0", + "commit": "62431dbd033bf1be2fe87fbc526df28084214e49", + "built_at": "2026-09-07T21:49:44Z", + "protocol": 22, + "endpoint_generation": 1, + "tag": "preview-2026-09-08-62431dbd033b", + "assets": { + "linux-x86_64": { + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-08-62431dbd033b/herdr-linux-x86_64", + "sha256": "3f56cab5d1d27b87f6cd2addfa3809bf48a58b345b13746419d1b8e951e0667d" + }, + "linux-aarch64": { + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-08-62431dbd033b/herdr-linux-aarch64", + "sha256": "47f075a0531ab6c36ec8f3144e634ea02c1307a1de405e29db3fd4d80efeb068" + }, + "macos-x86_64": { + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-08-62431dbd033b/herdr-macos-x86_64", + "sha256": "6b68aaf84ad62198773d9a710dea3d364dbd6c1ff65abdff8eb6e5a71a57830d" + }, + "macos-aarch64": { + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-08-62431dbd033b/herdr-macos-aarch64", + "sha256": "d6b6ad08961e7b491fc19a4cd8570f0231734672cfc4d6c0db6327437ac11065" + }, + "windows-x86_64": { + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-08-62431dbd033b/herdr-windows-x86_64.zip", + "sha256": "5904ceb4fdb3aa4c377f88ee8d2676bb39fcf62c6a8f034e6147cf21a98e6cb0", + "format": "zip" + } + } + }, "2026-09-06-9e9bc8a14466": { "base_version": "0.8.2", "commit": "9e9bc8a144667a6b7debfd4f0c7a31ff0e11493a", diff --git a/docs/preview/website/src/content/docs/agent-automation.mdx b/docs/preview/website/src/content/docs/agent-automation.mdx index 237162fb..068d1c9e 100644 --- a/docs/preview/website/src/content/docs/agent-automation.mdx +++ b/docs/preview/website/src/content/docs/agent-automation.mdx @@ -73,9 +73,11 @@ herdr agent rename w1:p2 reviewer Pane input addresses the terminal regardless of its current occupant. Agent input resolves the live agent and rejects the operation if that agent no longer controls the pane. -`agent prompt --wait` submits immediately unless the agent is already `blocked`, in which case it returns `agent_blocked` without starting the wait. If an accepted prompt starts from another non-working state, Herdr must observe `working` or `blocked` within five seconds. Otherwise, it returns `agent_prompt_stalled`; if the caller timeout expires first, it returns the normal `timeout` error. This prevents unrelated `idle`, `done`, or session changes from completing the wait. After Herdr observes activity, it waits for the requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. Standalone `agent wait` observes the current agent and returns immediately if its status already matches. Both commands default to `idle`, `done`, or `blocked`. Repeat `--until` to accept several exact states, for example `--until idle --until done`; use `--until unknown` explicitly when needed. On `agent prompt`, `--until` requires `--wait`. +`agent prompt --wait` rejects an agent already `blocked` with `agent_blocked`, without sending input or starting a wait. Otherwise, it writes the prompt and delayed Enter as one ordered submission before waiting. For Codex on Windows, the delay grows with prompt size. The caller timeout includes submission time. If the prompt started from another non-working state, Herdr waits up to five seconds after submission to observe `working` or `blocked`. Otherwise, it returns `agent_prompt_stalled`; if the caller timeout expires first, it returns the normal `timeout` error. This prevents unrelated `idle`, `done`, or session changes from completing the wait. After Herdr observes activity, it waits for the requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. Standalone `agent wait` observes the current agent and returns immediately if its status already matches. Both commands default to `idle`, `done`, or `blocked`. Repeat `--until` to accept several exact states, for example `--until idle --until done`; use `--until unknown` explicitly when needed. On `agent prompt`, `--until` requires `--wait`. -`idle` means the agent is ready for input and its tab has been seen in the focused Herdr UI. `done` is the same underlying idle state after background work finishes, until that tab is focused or `pane focus` / `agent focus` targets it. Reading through the CLI does not mark it seen. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify its lifecycle confidently; it does not prove successful completion. Use exact `--until` states when that distinction matters. +`idle` and `done` both mean the agent is ready for input. The CLI/API uses the server's seen state: `done` is idle but not yet marked seen, explicit `pane focus` / `agent focus` commands mark the target seen, and reads do not. Each TUI client tracks viewed completions independently, so a client's Done badge can differ from the CLI or another client's badge. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify its lifecycle confidently; it does not prove successful completion. Use exact `--until` states when that distinction matters. + +A timeout or `agent_prompt_stalled` does not prove that no input was sent. Read the agent before retrying to avoid submitting the same prompt twice. IDs and agent names are scoped to one server; selecting another machine in the TUI does not retarget CLI commands running in an existing pane. `pane wait-output` does not interpret agent lifecycle. It polls the selected terminal snapshot and searches it immediately, so text that was already present can match. The default source name is `recent`; matching treats that source as unwrapped recent output from the latest 80 rendered terminal rows. `--lines` changes that row limit, and `--regex` uses Rust regular-expression syntax and matches one line at a time. diff --git a/docs/preview/website/src/content/docs/cli-reference.mdx b/docs/preview/website/src/content/docs/cli-reference.mdx index d82a550a..63642729 100644 --- a/docs/preview/website/src/content/docs/cli-reference.mdx +++ b/docs/preview/website/src/content/docs/cli-reference.mdx @@ -11,13 +11,9 @@ Most commands print JSON responses for deterministic automation in scripts. ```bash herdr # launch or attach to the default session -herdr --session work # launch or attach to a named session herdr --remote workbox # attach through SSH, using local keybindings -herdr --remote workbox --remote-keybindings server -herdr --remote workbox --handoff herdr --default-config # print default config herdr update # download and install from the configured channel -herdr update --handoff # opt into live handoff for supported running servers herdr completion zsh # generate a zsh completion script herdr channel show # print stable or preview herdr channel set preview # opt into preview builds @@ -25,6 +21,12 @@ herdr channel set stable # return a direct install to stable herdr --version # print version ``` +Optional launch and update settings: + +- Add `--session ` to use a named session instead of the default. +- Add `--remote-keybindings server` to remote attach to use server keybindings instead of local ones. +- Experimental live handoff requires explicit `--handoff` on `herdr --remote` or `herdr update`. It is not the normal setup or connection path; see [Updates](/docs/install/#update). + Status commands: ```bash @@ -48,19 +50,23 @@ with the installed binary. Use `--json` for the full JSON Schema document, or ## Saved SSH machines ```bash -herdr machine list [--json] -herdr machine add workbox --label "Build machine" [--remote-session agents] +herdr machine list +herdr machine add workbox --label "Build machine" herdr machine rename --label "New name" herdr machine disable herdr machine enable herdr machine remove ``` -`machine add` checks the remote installation's capabilities, installs or updates with approval only when needed, and starts the requested session's background server before saving. Compatible release versions do not need to match. Run setup in an interactive terminal when installation or restart approval is required; failed or cancelled setup does not save a profile. +By default, `machine add` uses the remote default session. Add `--remote-session ` only for a named session. `machine list` accepts optional `--json` for scripts. See [Connecting machines](/docs/connecting-machines/) for the full setup and connection guide. + +`machine add` checks the remote installation's capabilities, installs or updates with approval only when needed, and starts the requested session's background server before saving. Compatible release versions do not need to match. Run setup in an interactive terminal when installation or restart approval is required; failed or cancelled setup does not save a profile. Replacing a running server requires explicit approval with a default answer of No, and stops its pane processes. `machine add` never enables experimental handoff implicitly. Changes apply automatically to open local Herdr clients, normally within a second. Added or enabled machines connect in the background; renaming does not reconnect. Removing or disabling disconnects only that machine and leaves its remote sessions running. Removing the machine you are viewing returns to Local, or shows Local as unavailable until it reconnects. Each profile stores an opaque ID, label, SSH target, explicit remote session, and enabled state in client state. Herdr does not store passwords, private keys, or other SSH credentials. -Automatic connections and reconnects are non-interactive. If a host key, password, key passphrase, MFA step, install, update, or restart needs approval, the machine shows Attention instead of opening a hidden prompt. Run the standalone command printed by Herdr, such as `herdr --remote workbox --session agents --handoff`, to complete that setup in the foreground, then restart the client. +Automatic connections and reconnects are non-interactive. If a host key, password, key passphrase, MFA step, install, update, or restart needs approval, the machine shows Attention instead of opening a hidden prompt. Run the standalone command printed by Herdr, such as `herdr --remote workbox`, to complete that setup in the foreground, then restart the client. Include `--session ` only when the profile targets a named session. + +Workspace, tab, pane IDs, and agent names belong to a single server. Selecting a machine in the UI does not change the session or socket inherited by commands running in an existing pane. For remote automation, run the CLI on the intended host against the intended session and discover its IDs there. ## Shell completions @@ -327,9 +333,9 @@ Agent targets are either a unique live agent name or the pane ID that currently A successful start returns only after the expected agent owns the same terminal and is ready for interactive input. If detection reports `blocked` during startup, the command returns `agent_not_ready` immediately. The name remains available for `agent read` and `agent send-keys`, and becomes ready for prompts after detection reports `idle`. The default startup timeout is 30000 milliseconds; explicit values must be greater than 3000 and no more than 300000. -`agent prompt` honors live bracketed-paste mode and sends text followed by encoded Enter after a short delay, including while the agent is working. If the agent is already `blocked`, it returns `agent_blocked` without sending input. With `--wait`, an accepted prompt sent from another non-working state must produce an observed `working` or `blocked` state within five seconds or Herdr returns `agent_prompt_stalled`; if the caller timeout expires first, Herdr returns the normal `timeout` error. This prevents unrelated `idle`, `done`, or session changes from completing the wait. After activity is observed, it waits for the first requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. `--until` narrows the matching states and is rejected unless `--wait` is also present. Standalone `agent wait` returns immediately when the current status matches. Both default to `idle`, `done`, or `blocked`; use `--until unknown` explicitly when needed. +`agent prompt` honors live bracketed-paste mode and writes text followed by delayed Enter as one ordered submission, including while the agent is working. Success without `--wait` acknowledges the writes, not the start of a turn. For Codex on Windows, the delay grows with prompt size; the caller timeout includes submission time. If the agent is already `blocked`, it returns `agent_blocked` without sending input. With `--wait`, a prompt sent from another non-working state has up to five seconds after submission to produce an observed `working` or `blocked` state or Herdr returns `agent_prompt_stalled`; if the caller timeout expires first, Herdr returns the normal `timeout` error. This prevents unrelated `idle`, `done`, or session changes from completing the wait. After activity is observed, it waits for the first requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. `--until` narrows the matching states and is rejected unless `--wait` is also present. Standalone `agent wait` returns immediately when the current status matches. Both default to `idle`, `done`, or `blocked`; use `--until unknown` explicitly when needed. -`idle` means ready for input after its tab has been seen in the focused Herdr UI; `done` is the same underlying idle state after unseen background work completes. Focusing that tab or targeting it with `pane focus` / `agent focus` marks it seen; reading it through the CLI does not. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify it confidently, not that its work succeeded. +`idle` and `done` both mean ready for input. The CLI/API uses the server's seen state: `done` is idle but not yet marked seen, explicit `pane focus` / `agent focus` commands mark the target seen, and reads do not. Each TUI client tracks viewed completions independently, so its Done badge can differ from the CLI or another client. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify it confidently, not that its work succeeded. `agent send-keys` sends logical terminal keys such as `enter`, `up`, `esc`, or `ctrl+c`. Herdr validates every key before writing any bytes. `agent read` reads the resolved terminal stream, and `agent rename` names an already detected agent. @@ -373,6 +379,8 @@ Use `pane wait-output` for normal commands and servers. Use `agent wait` for cod `pane wait-output` checks the selected snapshot immediately, including output that already exists, then polls until it matches. The default source name is `recent`; matching treats it as unwrapped recent output from the latest 80 rendered terminal rows. `--lines` changes that row limit. `--match` finds a literal substring on one line, and `--regex` uses Rust regular-expression syntax and also matches one line at a time. +A timeout or `agent_prompt_stalled` does not prove the prompt was never delivered. Inspect the agent before retrying. + `pane wait-output` and `agent wait` wait indefinitely when `--timeout` is omitted. For `agent prompt --wait`, the settled-state wait is indefinite after activity is observed or when the prompt starts in `working`; a non-working prompt still returns `agent_prompt_stalled` after five seconds without observed activity. A timeout or server error is emitted as JSON on stderr with exit status 1. CLI usage errors exit with status 2. ## Integrations diff --git a/docs/preview/website/src/content/docs/concepts.mdx b/docs/preview/website/src/content/docs/concepts.mdx index 7641b17f..c45ec545 100644 --- a/docs/preview/website/src/content/docs/concepts.mdx +++ b/docs/preview/website/src/content/docs/concepts.mdx @@ -48,6 +48,8 @@ Agent states are: | `idle` | The agent is finished or waiting and has been seen. | | `unknown` | Herdr cannot confidently classify the state. | +Each client tracks which completions it has displayed. Viewing a completion in one client does not clear another client's Done badge. CLI/API statuses use the server's seen state, so they need not match a particular client's badge; both `idle` and `done` mean ready for input. + ## Session A session is a persistent Herdr server namespace. The default `herdr` command attaches to the default session. diff --git a/docs/preview/website/src/content/docs/configuration.mdx b/docs/preview/website/src/content/docs/configuration.mdx index 63ce3186..a8050d2b 100644 --- a/docs/preview/website/src/content/docs/configuration.mdx +++ b/docs/preview/website/src/content/docs/configuration.mdx @@ -50,6 +50,8 @@ You can also open the global menu in Herdr and choose `reload config`. Reload applies most UI settings without restarting panes. Startup-only settings still need a restart. +Themes, sidebar layouts, copy behavior, and other presentation settings come from the client's local config, including when viewing an SSH machine. Pane defaults, worktrees, integrations, and custom commands belong to the server where the panes run. The UI's `reload config` action reloads both the client's local settings and the selected server's config. Local keybindings reload too; `--remote-keybindings server` instead uses the selected server's keybindings. + ## Headless terminal size When no client is attached, the server uses a 120×40 virtual terminal for layout and newly created panes. Change that fallback for headless orchestration with: @@ -298,6 +300,8 @@ The active palette is applied in this order: built-in theme, `[theme.custom]`, t The sidebar is the main Herdr dashboard. Search `ui.` in the [Config reference](/docs/config-reference/) for sizing, collapsed mode, Agent panel ordering, mouse behavior, pane borders, and other presentation settings. +`ui.pane_borders` accepts `"auto"` (the default, borders only for split panes), `"always"` (also frame a single pane), or `"off"`. A single-pane frame requires `ui.pane_outer_borders = true`, because all its edges are outer edges. Existing boolean values remain valid: `true` means `"auto"` and `false` means `"off"`. + Set `tab_bar_position = "bottom"` under `[ui]` to place the desktop tab row below the terminal panes. Prefix, Navigate, Copy, and Resize mode bars temporarily replace the bottom tab row while active. The default is `"top"`. Configure an ordered tmux-style status area at the right edge of the tab row: @@ -400,6 +404,25 @@ rows = [ `fg` accepts strict `#RGB` or `#RRGGBB`. `bold` and `dim` accept booleans. Omitted fields preserve the token's contextual style; explicit `false` removes that modifier. Styling applies to one occurrence, so the same token may look different in another row or agent override. A foreground override replaces all semantic foregrounds inside that occurrence: for example, styled `git_status` ahead and behind counts use one color instead of their default green and red. Token styles never change separators or row backgrounds. +Text-valued tokens also accept up to 16 ordered `rules`. Each rule contains exactly one condition—`equals`, `contains`, `starts_with`, `gt`, or `lt`—and optional `fg`, `bold`, and `dim` overrides: + +```toml +[ui.sidebar.agents] +rows = [ + ["state_icon", "workspace", "tab"], + [{ token = "machine", fg = "#fff", rules = [{ equals = "Local", fg = "#f55" }, { equals = "Fedora", ignore_case = true, fg = "#51a2da" }] }, "agent"], + [{ token = "$load", fg = "#fff", rules = [{ gt = 80, fg = "#f55", bold = true }, { gt = 50, fg = "#fc0" }] }], +] +``` + +The first matching rule wins. Its specified style fields override the occurrence's defaults; unspecified fields inherit them. If no rule matches, the defaults remain. Matching uses the full token value before display truncation and does not change its text, separators, or visibility. A rule with no style fields stops matching and keeps the defaults. + +`equals`, `contains`, and `starts_with` take strings and are case-sensitive. Add `ignore_case = true` for ASCII case-insensitive matching; non-ASCII characters remain case-sensitive. Empty strings follow ordinary string matching: empty `equals` matches only an empty value, while empty `contains` or `starts_with` matches any present value. + +`gt` and `lt` take finite numeric thresholds and compare strictly greater or less, not equal. Values must parse completely as finite numbers; decimal and exponent forms work, but whitespace, units, `NaN`, and infinity do not match. `ignore_case` is not accepted on numeric rules. Comparisons use floating-point numbers, not exact large-integer arithmetic. + +Rules work with text-valued built-ins and custom `$name` tokens in Agent rows, `rows_by_agent` overrides, and Space rows. Custom tokens match their reported value: `$load` reporting `"90"` selects red and bold above, `"60"` selects yellow, and `"90%"` keeps white. Unreported tokens still disappear. `state_icon` and composite `git_status` accept fixed styles only, not rules. Unknown conditions and malformed rules are rejected when loading config; regex, fuzzy matching, and scripts are not supported. + `row_gap` controls the blank terminal rows between entries, independently for the Agent and Space panels. It defaults to `0`, which packs entries together; set it to `1` to restore the previous spacing. It does not add spacing between the content lines declared in `rows`. Consecutive indented worktree children remain packed as one Space group. Override the complete Agent layout for a known agent under `rows_by_agent`: diff --git a/docs/preview/website/src/content/docs/connecting-machines.mdx b/docs/preview/website/src/content/docs/connecting-machines.mdx new file mode 100644 index 00000000..e922e3a2 --- /dev/null +++ b/docs/preview/website/src/content/docs/connecting-machines.mdx @@ -0,0 +1,100 @@ +--- +title: Connecting machines +description: Work across Local and saved SSH machines in one Herdr window, with shared agent navigation and independent reconnects. +--- + +Keep your local work and remote agents in one Herdr window. Save an SSH machine once, then switch between its workspaces and Local without opening another client. The agent list includes connected machines, so you can see where work is running and which agent needs an answer. + +Each machine keeps its own Herdr server, sessions, and running processes. A lost connection to one machine does not disconnect the others. + +## Before you connect + +You need normal SSH access to the remote machine. Verify it first: + +```bash +ssh workbox +``` + +`workbox` can be a host from your SSH config. You can also use a target such as `ssh://you@server:2222`. + +Multi-machine connections are supported on Linux and macOS clients, connecting to Linux and macOS servers on x86_64 or aarch64. Multi-machine connections are not yet verified or supported on Windows; standalone `herdr --remote` remains supported on Windows. Native Windows servers are not supported as SSH targets. See [Remote attach over SSH](/docs/persistence-remote/#remote-attach-over-ssh) for SSH configuration, authentication, and custom binaries. + +## Add a machine + +Run setup in an interactive terminal so Herdr can ask before installing or replacing anything: + +```bash +herdr machine add workbox --label "Build machine" +``` + +This uses the remote default session. A machine profile targets one remote session; it does not combine every session on the host. + +To use a named session instead, add the optional `--remote-session` flag: + +```bash +herdr machine add workbox --label "Build machine" --remote-session agents +``` + +Herdr checks both the installed binary and the running server. It starts the requested background server before saving the profile. Compatible client and server versions do not have to match. Missing or incompatible installations go through an approval-based setup. When the running server needs replacement, setup asks before stopping it and its pane processes, then starts the compatible server. The default answer is No. If installation and replacement are both needed, one confirmation covers them. `machine add` does not use experimental live handoff. Cancelling or failing setup leaves the profile unsaved. + +Run `herdr` to open the UI. If a local client is already open, added and enabled machines normally appear within a second and connect in the background without changing your selection. An in-progress machine switch finishes before profile changes are applied. The remote server keeps running after setup exits. + +## Switch between machines + +Choose a machine or one of its workspaces in the sidebar. The selected machine receives your pane input and terminal size, and supplies the visible terminal content and graphics. Other connected machines keep updating their workspace information, agent states, and notifications without streaming their pane screens. + +Local opens immediately on startup without waiting for SSH connections. A stalled machine cannot hold up another machine's input. Multiple Herdr clients can also view different tabs on the same server independently; see [Client and server](/docs/concepts/#client-and-server) for shared-tab sizing. + +When a connection is lost, the last workspace and agent state remains visible but dimmed. That is cached information, not live state. Input and navigation into those cached panes stay disabled until a fresh connection and matching screen arrive. Reconnecting never takes selection away from the machine you are using. + +## Rename, disable, or remove + +Read profile IDs from the list rather than deriving them from labels or hostnames: + +```bash +herdr machine list +herdr machine rename --label "New name" +herdr machine disable +herdr machine enable +herdr machine remove +``` + +For scripts, add `--json` to `machine list`. + +Renaming changes the displayed label without reconnecting. Disabling keeps the profile for later; removing forgets it. Both disconnect only that machine from the client and leave its remote sessions and agents running, even if the host is unreachable. + +Removing or disabling the machine you are viewing returns you to Local. If Local is unavailable, Herdr shows that and retries its connection instead of selecting a different remote machine. With enabled saved machines, the client can remain usable even if Local fails or restarts. + +## Connection problems + +- **Reconnecting:** Herdr retries with bounded backoff after a network interruption, sleep, or SSH failure. SSH connections are checked for application-level activity and probed when quiet, so a broken connection does not stay Online indefinitely. Local detects native connection closure or failure instead of using remote health probes. +- **Attention:** The target needs an action that cannot be completed in the background, such as host-key approval, authentication, or a compatible server. Other machines remain usable. +- **Saved-machine file error:** An unreadable or invalid catalog leaves current connections unchanged. Herdr shows a notice and automatically retries reading it. + +Background connections never answer prompts or install, update, restart, or hand off a server. For Attention, run the standalone setup command shown by Herdr in an interactive terminal, for example: + +```bash +herdr --remote workbox +``` + +Use your profile's target. If you chose a named session when adding it, include the optional `--session ` here too. Follow any approval prompts, then restart the client to retry the Attention connection. Do not stop a running server merely because its version differs from the client. + +If authentication fails, check ordinary SSH first. For a passphrase-protected key, load it with `ssh-add` before starting Herdr's non-interactive background connections. + +## Settings and automation + +The UI uses the client's local theme, sidebar settings, and keybindings by default. Custom commands and plugins advertised by the selected server still run there. Herdr does not copy local command plugins, configuration, executables, or secrets onto SSH hosts. Missing remote commands fail visibly. Use the UI's `reload config` action after editing client settings; see [Configuration](/docs/configuration/#reload-config). + +Default agent rows show a `machine` token when multiple machines are present. Existing custom rows are preserved; add `machine` explicitly if you want that label in your layout. [Sidebar row layouts](/docs/configuration/#sidebar-row-layouts) also support conditional colors for machine labels. + +Workspace, tab, pane IDs, and agent names are scoped to one server. Two machines may both contain `w1:p1` or an agent named `reviewer`. Selecting a machine in the UI does not retarget CLI commands running in an existing pane: they still use that pane's inherited session and socket. For remote automation, run commands on the intended host against the intended session and read its IDs there. + +## Updates and saved data + +Saved profiles contain only an opaque ID, label, SSH target, explicit remote session, and enabled state. Herdr does not store passwords, private keys, agent tickets, or SSH control sockets in the catalog. Authentication stays with OpenSSH. + +The client and server negotiate compatibility rather than requiring identical versions. Saved-machine connections additionally need the server's `surface_interest` and `health_check` capabilities. Older servers without those capabilities show Attention until explicitly updated, even if a standalone attach works. Other missing server methods disable only their corresponding actions. + +Updating a compatible client does not replace the running remote server or stop its agents. When you need new server-side behavior, update that server explicitly. Normal replacement asks before stopping the server and its pane processes. + +Live handoff is experimental and opt-in. For a supported server that needs replacement during standalone setup, you can explicitly add `--handoff` to `herdr --remote`; it is not needed for normal connections or authentication fixes. See [Update](/docs/install/#update) for restart and handoff choices, and [Session state and restore](/docs/session-state/) for what survives each operation. diff --git a/docs/preview/website/src/content/docs/how-to-work.mdx b/docs/preview/website/src/content/docs/how-to-work.mdx index 6e74e59d..f35f8c7e 100644 --- a/docs/preview/website/src/content/docs/how-to-work.mdx +++ b/docs/preview/website/src/content/docs/how-to-work.mdx @@ -77,7 +77,7 @@ herdr --remote workbox herdr --remote ssh://you@server:2222 ``` -Your local Herdr acts as a thin client. It connects over SSH, starts or attaches to the remote Herdr server, and streams the UI back to your local terminal. +The remote server keeps the panes running and sends their terminal content and session state over SSH. Your local Herdr draws the UI using your local theme and presentation settings. Use this path when you want the remote session to feel local. The client runs on your machine, so local desktop features such as image clipboard paste can be bridged to the remote server. If you SSH first and run `herdr` on the server, Herdr runs entirely on that server and cannot read your local desktop clipboard. @@ -98,6 +98,6 @@ herdr --remote workbox ## Which path to use -Use `herdr` for local work. Use `ssh you@server` then `herdr` when you want Herdr to behave like tmux on that remote shell or when you are using a phone SSH client. Use `herdr --remote ` when you want a local thin client for a remote session, including local clipboard image paste bridging. +Use `herdr` for local work. Use `ssh you@server` then `herdr` when you want Herdr to behave like tmux on that remote shell or when you are using a phone SSH client. Use `herdr --remote ` for a local UI attached to one remote session, including local clipboard image paste. To keep Local and several SSH machines in one window, save them with `herdr machine add --label