Install PK-Herdr

Next docs describe unreleased work from master. Stable docs remain at /docs/.

PK-Herdr ships stable binaries for Linux and macOS. Native Windows support is preview-only beta.

Install

On Linux or macOS, run:

curl -fsSL https://herdr.pkking.computer/install.sh | sh

On Windows preview beta, install the preview channel:

powershell -ExecutionPolicy Bypass -c "irm https://herdr.pkking.computer/install.ps1 | iex"

The installer downloads the right release binary for your platform and places it on your PATH. The Windows installer defaults to preview, writes that channel to PK-Herdr’s config, uses versioned install folders, and updates a current junction, so updates do not need to overwrite a running pk-herdr.exe.

Package managers

Homebrew and the mise registry currently track upstream Herdr, not this fork. Use the direct installer above for pk-herdr fork updates.

If you already use mise and want this fork explicitly, install from GitHub:

mise use -g github:kingkillery/pk-herdr

Install with Nix

If you already use Nix, PK-Herdr provides a flake that builds PK-Herdr from source:

nix run github:kingkillery/pk-herdr/v0.x.y
nix build github:kingkillery/pk-herdr/v0.x.y
nix profile install github:kingkillery/pk-herdr/v0.x.y

Replace v0.x.y with the latest release tag. You can omit the tag to track master, but release tags are recommended for normal installs.

The flake also exposes a development shell:

nix develop github:kingkillery/pk-herdr

Update through the same Nix workflow you used to install PK-Herdr. For a profile install, list your profile entries and upgrade the PK-Herdr entry:

nix profile list
nix profile upgrade <index-or-name>

If PK-Herdr is an input in your own flake, update that input and rebuild your system, Home Manager, or development environment:

nix flake update herdr

Download manually

The fork’s release binaries are published on GitHub Releases and served through the compatibility download endpoint at https://herdr.pkking.computer/releases/download/<tag>/<asset>. The installer fetches channel manifests from https://herdr.pkking.computer/latest.json (stable) or https://herdr.pkking.computer/preview.json (preview). Download the asset that matches your system, mark it executable, and put it on your PATH.

Stable binaries

System	Asset
Linux x86_64	herdr-linux-x86_64
Linux aarch64	herdr-linux-aarch64
macOS Intel	herdr-macos-x86_64
macOS Apple silicon	herdr-macos-aarch64

The current stable version and every asset URL are listed in latest.json, which is what the installer script reads.

On Linux or macOS, make it executable and move it somewhere on your PATH.

chmod +x herdr-linux-x86_64
mv herdr-linux-x86_64 ~/.local/bin/pk-herdr

Windows beta downloads

Windows binaries are published only on preview releases while native Windows support is in beta. Use the preview installer above for normal testing, or download the Windows asset from the compatibility endpoint.

System	Asset
Windows x86_64 beta	herdr-windows-x86_64.zip

The archive contains pk-herdr.exe and its app-local ConPTY runtime. Keep the extracted directory together; copying only pk-herdr.exe silently falls back to the system ConPTY.

The current build id and every asset URL are listed in the manifest at https://herdr.pkking.computer/preview.json, which is the source of truth for the preview channel.

Remote install

The installer scripts, channel manifests, and compatibility download endpoint are hosted at the custom domain (https://herdr.pkking.computer), with binaries backed by the fork’s GitHub Releases. You can push the same installer to any Linux or macOS host over SSH and attach from your local machine. pk-herdr --remote does not support Windows hosts yet — from Windows, SSH into the server and run pk-herdr there directly.

To use pk-herdr --remote, the local client must also be the pk-herdr fork. Otherwise the remote bootstrap will pull binaries from the upstream channel. Install the local fork client first:

curl -fsSL https://herdr.pkking.computer/install.sh | sh

Then push the installer to a remote host over SSH:

# one-line install on a remote host (Linux/macOS only)
ssh user@host 'curl -fsSL https://herdr.pkking.computer/install.sh | sh'

# install to a custom directory on the remote host
ssh user@host 'curl -fsSL https://herdr.pkking.computer/install.sh | HERDR_INSTALL_DIR=$HOME/.local/bin sh'

Attach from your local machine:

pk-herdr --remote user@host
# or via SSH config alias
pk-herdr --remote workbox

pk-herdr --remote reuses an existing remote pk-herdr on $PATH when its protocol version matches. If the host has no matching binary, interactive runs prompt to install one to ~/.local/bin/pk-herdr from the fork’s latest manifest; non-interactive runs fail instead of mutating the host. The download is validated against the manifest asset URL prefix and refused if the binary is not served through the fork’s compatibility download endpoint. For named remote sessions, custom remote binaries, direct terminal attach, and live handoff, see Persistence and remote access.

Updates on the remote host use the same channel:

ssh user@host 'pk-herdr update'

Verify

Start PK-Herdr:

pk-herdr

If your shell cannot find pk-herdr, restart the terminal or check that the install directory is on your PATH.

Update

PK-Herdr checks for new releases and notifies you in the app. You can update manually:

pk-herdr update

pk-herdr update is for installs managed by the pk-herdr direct installer. Homebrew and the mise registry track upstream Herdr; switch to a direct kingkillery/pk-herdr install if you want fork-only updates. Nix installs update through the same github:kingkillery/pk-herdr flake workflow you used to install them.

On Linux and macOS, PK-Herdr uses the stable update channel by default. To opt into preview builds from master, set the channel:

pk-herdr channel set preview

Switch Linux and macOS direct installs back to stable the same way:

pk-herdr channel set stable

For direct installs, changing channels also checks that channel and installs its latest binary. If that update fails, run pk-herdr update to retry from the configured channel.

Preview builds are manually published GitHub prereleases from the current development branch. They are useful when you want fixes before the next stable release, but they can regress. Homebrew and mise registry installs do not receive pk-herdr preview builds.

Windows beta builds are preview-only for now. pk-herdr channel set stable is rejected on Windows until stable Windows releases are available.

By default, pk-herdr update installs the new binary and leaves compatible running sessions alone. If an update changes PK-Herdr’s client/server protocol, PK-Herdr asks whether to stop the old server after installing. Stop the old server to use the new version. Stopping exits pane processes. For the default session, run pk-herdr server stop, then run pk-herdr again. For a named session, run pk-herdr session stop <name>, then run pk-herdr session attach <name> again.

To opt into experimental live server handoff for supported running sessions, run:

pk-herdr update --handoff

Live handoff does not apply to package-manager updates. For Nix installs, update with the same github:kingkillery/pk-herdr flake workflow, then restart that PK-Herdr session when you are ready to use the new server. If a running session still uses the old server, stop it with pk-herdr server stop or pk-herdr session stop <name>, then run PK-Herdr again.

Requirements

Stable PK-Herdr releases support Linux and macOS. Native Windows builds are preview-only beta releases; see Windows beta for supported workflows and known limitations.