Skip to content

Windows support

Native Windows support is generally available.

Herdsman on Windows uses ConPTY and Windows process/runtime behavior instead of the Unix PTY model Herdsman was originally built around. Most core workflows are supported, but some capabilities differ from Linux and macOS or remain platform-dependent. Windows may receive more platform-specific fixes as those remaining gaps close.

Install Herdsman natively on Windows with PowerShell:

Terminal window
powershell -ExecutionPolicy Bypass -c "irm https://remziduzagac.github.io/herdsman/install.ps1 | iex"

If endpoint security blocks that fileless PowerShell command, open Command Prompt and run:

Terminal window
curl.exe -fsSLo install.cmd https://remziduzagac.github.io/herdsman/install.cmd && install.cmd && del install.cmd

Windows builds are available through both stable and preview update channels. New installs use stable by default, and stable is recommended for normal use. Existing preview installs stay on preview until you run herdsman channel set stable. If an older preview build rejects that command, run herdsman update once on preview and retry. Preview provides newer, less-tested fixes from master and may regress; opt in with herdsman channel set preview only when you want that tradeoff.

The installer stores releases under %USERPROFILE%\.herdsman\packages\standalone\releases, puts the active versioned release directory on PATH, keeps %LOCALAPPDATA%\Programs\Herdsman\bin as a stable compatibility alias, and retains a small number of older releases so running processes do not block updates.

For internal testing, HERDSMAN_MANIFEST_URL can point the installer at a custom manifest instead of Herdsman’s stable or preview manifest. Set HERDSMAN_CHANNEL=preview with a custom preview manifest.

Capability Status
Local persistent sessions supported
Native panes through ConPTY supported
Windows Terminal / PowerShell app attach supported
herdsman --remote and saved SSH machines to Linux/macOS/Windows hosts supported; interactive attach and saved-machine setup can install or update Windows packages after confirmation; background reconnect only discovers installed packages
Remote clipboard images and image-file drops supported
cmd.exe panes supported
Native keyboard and mouse input supported
Startup cwd and workspace labels supported
Pane launch cwd supported
Agent command discovery supported
Supported agent self-report integrations supported
Agent process-tree detection supported
Git/worktree detection from known cwd supported
System notifications and MP3 sounds supported
Plugins preview
Pane screen history supported
Nested launch override supported

Local persistent sessions continue running after the client detaches or its terminal window closes. Servers and pane processes launched through Windows OpenSSH also survive logout; run herdsman again to reconnect.

Elevated Windows servers require an administrator client by default, including servers started through an elevated SSH login. Ordinary servers accept clients from ordinary and administrator terminals belonging to the same account; attaching never changes the server’s privileges.

To deliberately share elevated sessions with ordinary clients, set:

[server]
allow_unelevated_clients = true

This Windows-only setting is off by default and applies when a new server starts, including automatic startup. Reloading config does not change a running server’s access policy. You can instead enable sharing for one server process from an administrator terminal with herdsman server --allow-unelevated-clients (or herdsman --session <name> server --allow-unelevated-clients for a named session). The flag enables sharing even when the config setting is false.

Either option allows ordinary local processes belonging to that account to control administrator panes; other accounts remain excluded. The flag must be supplied again after a restart unless sharing is enabled in config. Existing servers retain their previous access policy until stopped and restarted with the updated build; stopping closes their panes. Config and recovery files retain their account-based permissions.

Windows agent process detection scans descendants of the pane shell and recognizes direct agents plus common command wrappers, including npm/Node and Git Bash process chains. It follows Git Bash-launched agents across emulated exec boundaries, but it is not the same as Unix foreground process-group detection.

Windows integration installation currently supports Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, Devin CLI, OpenCode, Kilo Code CLI, Droid, Kimi Code CLI, Qoder CLI, and Antigravity CLI. Availability is narrower than on Unix; Herdsman hides or rejects integrations whose install format is not supported on Windows.

Plugins support windows as a manifest platform in preview. GitHub install, local link, build commands, actions, events, and plugin panes are best-effort on Windows. Commands are argv commands and must be Windows-compatible; Node package shims such as npm, bun, and node are expected to work when they are on PATH, while Unix-only examples using sh or Bash need Windows-specific alternatives. Platform filters skip unsupported build commands and return platform_unsupported for unsupported actions or panes.

Capability Status
Live cwd after shell cd partial
Live cwd via shell integration/OSC7 supported
Clipboard image paste to agents in local panes terminal/agent dependent
CJK IME composition anchoring partial
Prefix input-source switching (Korean IME) partial
Kitty graphics rendering terminal dependent
Host cursor rendering partial

Herdsman can launch panes in the right directory and create the initial workspace from the directory where you started Herdsman. After startup, the process field Herdsman can inspect does not reliably track later logical cd changes in PowerShell. Use Herdsman integrations or prompt shell integration for live cwd reporting.

During herdsman --remote, the configured remote image paste key reads a Windows clipboard image and transfers it to the remote host. Dropping one local image file into Windows Terminal also transfers that file and pastes its remote path.

Prefix input-source switching is available as an opt-in experiment for the Korean IME. It switches Hangul input to English while prefix commands are active and restores the previous mode afterward:

[experimental]
switch_ascii_input_source_in_prefix = true

Other Windows IMEs are not supported by this option yet. See Configuration.

Some Windows agents can receive ctrl+v and read clipboard images directly. Herdsman’s own clipboard-image reader is not wired into local native Windows panes, so agent-native image paste remains dependent on the terminal and agent. Agent image-paste shortcuts such as alt+v do not add a Herdsman-managed local clipboard bridge. Remote clipboard image bridging is supported separately through herdsman --remote to Linux, macOS, and Windows hosts.

Kitty graphics is enabled by default and depends on the outer terminal. Herdsman emits Kitty graphics protocol output on Windows as it does on other platforms. This path has been exercised with Windows WezTerm hosting Herdsman through WSL, but native Windows terminal and ConPTY combinations are not all verified. Windows Terminal does not expose the Kitty graphics path Herdsman uses. Set [terminal].kitty_graphics = false if the outer terminal mishandles graphics output.

Herdsman relies on ConPTY for native Windows panes. The Windows terminal cursor path can expose intermediate positions while a multiplexer repaints the screen. A native cursor may flicker, jump, or briefly remain at an old position during active output. This behavior also reproduces in other native Windows terminal multiplexers and with direct VT cursor-position stress tests, so Herdsman cannot eliminate it while preserving native cursor behavior.

To prioritize visual stability, the default host_cursor = "auto" draws Herdsman’s cursor as terminal cell content on native Windows and WSL. Other Linux and macOS clients continue to use the native terminal cursor. The drawn Windows cursor is steady and non-blinking, but it does not provide the outer terminal’s native blink, shape, or cursor color.

Windows does not use a drawn cursor to position IME composition and candidate UI. Korean, Japanese, or Chinese IME UI may therefore appear at the wrong location. If this affects you, opt back into the outer terminal cursor:

[ui]
host_cursor = "native"

Native mode restores the IME anchor, but it can reintroduce occasional cursor flicker, jumps, or stale cursor positions during active output.

Windows terminals do not all report modified keys in the same shape. Herdsman preserves mouse reporting and ctrl+j in Windows Terminal and Alacritty on Windows. The native Windows input path also preserves physical key presses, repeats, releases, standalone Escape, and shift+enter through default ConPTY panes. Modified keys still depend on the outer terminal reporting a distinct key event; if it reports shift+enter as plain Enter, Herdsman can only forward plain Enter.

Windows packages include Microsoft’s current app-local ConPTY runtime because the system ConPTY on older Windows 10 builds drops Kitty keyboard protocol sequences used by agents such as Kimi and Pi. Set HERDSMAN_WINDOWS_CONPTY=system before starting Herdsman only when diagnosing a compatibility problem with the bundled runtime.

Herdsman’s pane text copy works on Windows. Drag-select text inside a pane to copy through Herdsman.

For text paste, use ctrl+shift+v in Windows Terminal. Multiline text paste is bracketed so shells and agent prompts receive it as one paste instead of submitting each line separately. Hold shift and right-click to use the outer terminal paste action instead of sending the click through Herdsman.

Windows clients also recover text when WezTerm wraps a complete sequence of Win32 character press/release pairs in raw paste markers. Mixed text and incomplete reports are not decoded by this compatibility rule. Literal clipboard text consisting entirely of matching Win32 reports is indistinguishable from this encoding and is decoded too.

Capability Status
Direct terminal attach (herdsman terminal attach) unsupported
Live server handoff unsupported
Unix file-descriptor handoff unsupported
Unix foreground process groups unsupported
Herdsman clipboard image bridge in local native panes unsupported
Signed binary / SmartScreen avoidance unsupported

From Windows Terminal, use the same remote command as Linux and macOS:

Terminal window
herdsman --remote workbox

The target host can run Linux, macOS, or Windows. On Windows hosts, remote attach reuses a compatible package from PATH or the active managed release. Interactive direct attach and saved-machine setup prompt before installing or updating the complete package when needed. Background saved reconnect only discovers installed packages and cannot prompt for installation or updates. Herdsman uses the installed Windows OpenSSH client and your SSH configuration. Windows OpenSSH does not use Herdsman’s Unix control-socket reuse, so key authentication through Windows ssh-agent is recommended to avoid repeated prompts during remote setup.

Windows updates run through the Windows installer and update the active versioned release path. New terminals and reconnected SSH sessions receive that path; start Herdsman there to use the updated client. Compatible running servers keep their panes alive. Restart a server later only when you need server-side changes from the release. Live handoff is Unix-only.

Include:

  • Herdsman version.
  • Windows version.
  • Terminal app.
  • Shell, such as PowerShell or cmd.
  • Whether you used a named HERDSMAN_SESSION.
  • Relevant Herdsman logs.
  • Exact steps to reproduce.