layered-soul/skills/herdr-deployment/references/build-pitfalls.md

Herdr Build Pitfalls

Zig version: exact 0.15.2 required

Herdr vendors libghostty-vt which is compiled via zig build during cargo build. The vendored library has an exact Zig version check.

Wrong version → build error:

error: Your Zig version v0.17.0-dev does not meet the required build version of v0.15.2

# Also breaks with:
error: invalid builtin function: '@cImport'          # removed in 0.17
error: member function expected 4 argument(s), found 3  # readFileAlloc changed

Fix: Download Zig 0.15.2 from ziglang.org, extract to ~/.local/, symlink zig into ~/.local/bin/:

# Remove wrong version
rm -f ~/.local/bin/zig

# Download and install
wget https://ziglang.org/download/0.15.2/zig-linux-x86_64-0.15.2.tar.xz
tar -xf zig-linux-x86_64-0.15.2.tar.xz -C ~/.local/
ln -s ~/.local/zig-linux-x86_64-0.15.2/zig ~/.local/bin/zig

# Verify
zig version  # must print "0.15.2"

Debian apt does not have Zig

apt search zig finds no matching package. Manual download from ziglang.org is the only reliable path.

herdr --remote requires interactive terminal for first install

The remote mode prompts for install confirmation via stdin. Running non-interactively fails with:

Error: "matching remote herdr 0.6.2 is not installed at $HOME/.local/bin/herdr;
run from an interactive terminal to approve installation"

Workarounds (pick one):

1. Run from user's terminal:

   export PATH="/path/to/herdr/target/release:$PATH"
   herdr --remote <host>-ts-herdr
   

   Approve the prompt, TUI opens, quit with q.

2. Pre-install upstream binary on remote:

   ssh <host>-ts-herdr 'mkdir -p ~/.local/bin'
   ssh <host>-ts-herdr 'curl -L <release-url> -o ~/.local/bin/herdr && chmod +x ~/.local/bin/herdr'
   

   Then herdr --remote detects the existing binary and skips the prompt.

3. Use HERDR_REMOTE_BINARY env var to ship a local build:

   HERDR_REMOTE_BINARY=/path/to/herdr/target/release/herdr herdr --remote <host>-ts-herdr
   

FreeBSD is not a supported remote platform

RemotePlatform::from_uname() in remote.rs only matches "Linux" and "Darwin". FreeBSD returns "FreeBSD" which causes:

Error: unsupported remote platform: FreeBSD amd64

Do not use herdr --remote against osa or any FreeBSD host.