Manual install

From one Herdr workstation to usable Web AI development.

Role: manual/operator reference. The primary herdr-mcp installation protocol is written directly for the executing Agent; see Agent install and Agent installation. Use this page for manual inspection, troubleshooting, or understanding each stage. It no longer provides a product-specific prompt to copy into a named coding agent.

The goal is to connect a local workstation to ChatGPT / Web AI while keeping source code and real execution on the workstation.

Before installation#

1. Herdr dependency is self-repaired by `herdr-mcp install`#

You may inspect Herdr manually with:

herdr --version
herdr api schema >/dev/null

but those commands are diagnostic, not a first-install prerequisite. The normal herdr-mcp install path now resolves Herdr from HERDR_BIN, the stable per-user location, Homebrew//usr/local, or the current PATH. If Herdr is already installed, herdr-mcp verifies the CLI/API and attempts herdr update (using live handoff when a server is already running). If Herdr cannot be found, herdr-mcp downloads and runs the official installer from https://herdr.dev/. After the herdr-mcp service is installed it also verifies that the local Herdr Server/API is reachable; macOS uses the owned Supervisor/TCC-broker path, while Linux/Windows start the current-user Herdr server when needed.

The official installer remains the manual fallback for troubleshooting:

# macOS / Linux
curl -fsSL https://herdr.dev/install.sh | sh

# Windows
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

2. Decide which client path you need#

ChatGPT / another public Web AI → Cloudflare Edge + outbound Herdr Link;
local MCP clients only → loopback runtime can be used without Cloudflare;
browser extension → optional after the base Connector works, not a first-install prerequisite.

Supported platform boundary#

Use the GitHub Latest stable Release at https://github.com/whshang/herdr-mcp/releases. First-device worker bootstrap and existing-fleet worker connect are production-qualified on Apple Silicon macOS and native Debian-class Linux on both x86_64 and ARM64. Herdr-MCP 1.0 also enables first-device worker bootstrap on native Windows, including canonical device enrollment, Windows Credential Manager persistence, managed runtime activation, and Link reconciliation. Windows x86_64 and Windows ARM64 remain published 1.0 candidates rather than Production platforms: Windows x86_64 has been exercised on physical hardware for install/recovery and a real Connector conversation, while the exact final 1.0 candidate still requires a fresh first-device bootstrap record plus the remaining #394 promotion evidence. Windows ARM64 still has hosted-runner qualification only. Windows uses Herdr named pipes, Windows Credential Manager, current-user Startup-folder shortcut autostart, and detached user processes. The explicit herdr-mcp install path now owns Herdr dependency recovery on Windows too: it resolves or installs the official Herdr CLI, attempts the stable update, and verifies that the current-user herdr server is reachable. Herdr uninstall remains independent. Browser Native Messaging and product-level reinstall/uninstall remain outside the Windows physical-UAT claim. See the platform support matrix for the exact tested/not-yet-tested boundary.

For an older installation, follow Runtime self-upgrade. Upgrade the runtime in place; do not recreate a healthy Worker, device relationship, or ChatGPT Connector just to move to the current release.

Step 1: install the native herdr-mcp runtime#

Download the newest stable herdr-mcp binary for this platform from https://github.com/whshang/herdr-mcp/releases, put it on PATH, then run:

herdr-mcp install
herdr-mcp doctor
herdr-mcp status

install stages an immutable generation under ~/.config/herdr-mcp/runtime/ and points the user PATH entry at runtime/current/herdr-mcp. Normal users do not install the local runtime with a git clone, npm, or cargo.

On Debian, use the static musl release asset matching the machine architecture: x86_64-unknown-linux-musl for x86_64 or aarch64-unknown-linux-musl for ARM64. On Windows, use x86_64-pc-windows-msvc or aarch64-pc-windows-msvc to match the machine architecture. The Linux installer prefers systemd --user; when no user systemd manager exists it uses the managed user-process backend. On macOS, the service is a user LaunchAgent and Full Disk Access is granted only to the stable macOS-only broker at ~/.config/herdr-mcp/tcc-broker/herdr-mcp-broker; Linux and Windows do not use that TCC/FDA path. sudo does not replace macOS privacy permission.

On macOS, start with herdr-mcp permissions status. If it reports needs_setup, run herdr-mcp permissions setup, enable the exact stable broker in System Settings → Privacy & Security → Full Disk Access, then run herdr-mcp permissions verify. Do not probe ~/Documents before setup just to trigger macOS prompts. The host-capable broker is the stable TCC client for MCP protected-folder file and Git tools: its request surface is a fixed allowlist of protected-folder file/Git operations (fs_read, fs_list, fs_grep, fs_image, fs_edit, fs_write, fs_patch, git), not an arbitrary shell/exec surface. Native Herdr panes and Agents are governed by the TCC identity of their execution host: the managed herdr server is started through this host-capable broker, so panes and Agents beneath it reuse the broker identity, while a Herdr host started outside that managed path keeps that host's own TCC boundary. A normal first install therefore needs one Full Disk Access approval instead of separate approvals per process. Ordinary runtime updates preserve this broker; use permissions setup --upgrade-broker only for an explicit compatibility migration. macOS may separately ask once for Keychain access by the stable herdr-mcp-credential-helper; approve that one-time prompt and keep the helper stable across updates. Platform details live in CLI reference and Troubleshooting. Do not add public Edge while the local doctor is unhealthy.

Optional: fast semantic decisions#

A fast decision model is optional after the local runtime is healthy. herdr-mcp install points users to this capability without requiring it. TypeSafe.ai is the recommended reference because it speaks the generic decision protocol; it is not a product dependency. If you choose that reference, sign up at https://typesafe.ai/, create an API key, then run the setup command below.

herdr-mcp semantic setup
herdr-mcp semantic status

The setup command uses TypeSafe.ai / jev-latest only as defaults that can be overridden with --name, --protocol, --url, and --model. It reads the API key through hidden terminal input, verifies typed-decision routes before saving them, and stores local route credentials only in the mode-0600 runtime config. Skipping semantic setup leaves the deterministic runtime path unchanged.

Step 2: deploy the public Edge#

Cloudflare Workers Free is sufficient for Herdr and does not require a payment method. If you do not have a Cloudflare account, create the free account on the sign-in page; Google sign-in is the recommended shortest path.

When ChatGPT needs to reach the workstation over the Internet, use a Cloudflare Worker as the stable OAuth/MCP entry point. Keep workers.dev enabled as the zero-domain bootstrap/diagnostic origin, but when the selected Cloudflare Account already has a suitable active zone, prefer a dedicated Custom Domain such as herdr-mcp.example.com for the long-lived OAuth/MCP identity before Connector authorization. If no suitable zone exists or the user declines, continue on workers.dev without blocking installation.

For automated installation, the executing Agent follows Agent install / Agent installation directly; those protocols own Token scoping, Worker naming, secret injection, account choice, and the boundary for network blockers.

For a manual/operator deployment, use the installed runtime too:

herdr-mcp worker bootstrap

This command owns Worker naming, release-artifact verification, direct Cloudflare API upload, secrets, first-device enrollment, and readiness verification. In runtimes containing the trusted-DNS recovery, if a new workers.dev hostname cannot resolve locally, bootstrap tries Cloudflare DNS then Google DNS, verifies the returned address with the real TLS /health contract, and only then attempts to persist a Herdr-marked mapping for that hostname in the system hosts file. Unix may request sudo; Windows requires an elevated terminal when the hosts file is not writable. Failure to persist the mapping does not invalidate an already verified in-process bootstrap path. Ordinary installation does not require a source checkout, Node.js, npm, Wrangler, or wrangler.user.toml.

Keep these constraints:

Cloudflare API Token is an ephemeral process value, not a repository or log value;
keep workers.dev as the zero-domain bootstrap origin; when a suitable active zone is available, finalize a Worker Custom Domain before Connector authorization rather than using generic DNS Write;
keep LINK_SHARED_SECRET as a Worker secret;
the workstation makes outbound authenticated WSS and does not expose a public local port.

See Agent-assisted installation for the ordinary bootstrap contract. Cloudflare Edge deployment retains the source/Wrangler workflow only as a maintainer and deep-operations reference.

v0.4.8 `workers.dev` DNS recovery#

v0.4.8 predates automatic direct trusted-DNS persistence. If bootstrap has already created the Worker but fails because its workers.dev hostname does not resolve locally, do this before rerunning the resumable bootstrap; do not switch to the public Relay for first enrollment.

EDGE_ORIGIN="https://<worker>.<account-subdomain>.workers.dev"
HOST="${EDGE_ORIGIN#https://}"; HOST="${HOST%%/*}"

# Try Cloudflare DoH first. If its hostname also fails locally, retry the same
# request with --resolve cloudflare-dns.com:443:1.1.1.1, then 1.0.0.1.
curl --noproxy '*' -fsS -H 'accept: application/dns-json'   "https://cloudflare-dns.com/dns-query?name=${HOST}&type=A"

# If Cloudflare DoH is unavailable, try Google DoH; the same pinned form can
# use dns.google:443:8.8.8.8 and then 8.8.4.4.
curl --noproxy '*' -fsS -H 'accept: application/dns-json'   "https://dns.google/resolve?name=${HOST}&type=A"

Choose one returned IPv4 A address as IP, then validate that address before touching hosts:

curl --noproxy '*' -fsS --resolve "${HOST}:443:${IP}" "${EDGE_ORIGIN}/health"

Proceed only when TLS hostname validation succeeds and /health identifies the expected Herdr Worker/contract. Check /etc/hosts first; if an unmanaged entry already names this hostname, stop instead of overwriting it. Otherwise add exactly one marked mapping, approve sudo yourself, and rerun bootstrap:

grep -n "${HOST}" /etc/hosts || true
printf '%s	%s	# herdr-mcp workers.dev %s
' "$IP" "$HOST" "$HOST" | sudo tee -a /etc/hosts >/dev/null
herdr-mcp worker bootstrap

This changes only one Worker hostname. It does not change the system DNS server, proxy, network node, OAuth issuer, or MCP public origin. A later runtime containing automatic recovery can refresh its own marked entry when that mapping becomes stale.

Step 3: verify the Herdr Link#

herdr-mcp doctor
herdr-mcp link status

If workers.dev direct access fails, first let worker bootstrap / worker connect repair DNS with the verified single-host mapping above and retry direct Link. Reuse an existing local proxy only if direct transport still fails; keep the built-in signed shared Relay as the final fallback. Do not redeploy the Worker or change system DNS just to repair this hostname. Verify with doctor and link status.

Step 4: verify the public path#

herdr-mcp doctor
herdr-mcp link status
curl -fsS "${EDGE_ORIGIN}/health"
curl -s -o /dev/null -w '%{http_code}\n' "${EDGE_ORIGIN}/mcp"

An unauthenticated /mcp response of 401 can be correct. The useful checks are: local runtime healthy, Link connected, Edge /health reachable, and OAuth metadata reachable.

Step 5: add the herdr Connector in ChatGPT#

This is a human step. The coding agent should pause and guide the user:

open ChatGPT Settings → Account security & login and enable Developer mode;
open Plugins → Browse plugins, click the top-right + → Create APP, and create an MCP app. herdr is the recommended example name, but a custom App name is supported;
paste the complete deployed ${MCP_URL}, including the final /mcp;
complete OAuth in the browser; the approval page selects Chinese, English, or Japanese from the browser language and asks you to run the Terminal approval command before entering the six-digit code;
create or open a Project and work there;
in the first message of every new chat, use the composer + button to reference herdr, so the plugin is enabled for that conversation.

Then do a read-only test:

Inspect my Herdr projects. Read only; do not modify anything.

If herdr_inspect returns real workstation data, the base loop is usable.

See ChatGPT Connector.

Step 6: add the browser extension only when continuity is needed#

The browser extension adds Side Panel Control Center, workspace binding, long-conversation continuity, and queued next-turn messages. It is not required for the base MCP loop.

The extension has three current identities: STORE / STANDALONE / DEV. STORE is the ordinary-user path, STANDALONE is the fixed-identity GitHub/manual distribution path, and DEV is source-development only.

STORE: default ordinary-user path, fixed Chrome Web Store identity and Store updates;
STANDALONE: fixed non-Store identity for independent/GitHub distribution;
DEV: source development only, Load unpacked from repo/worktree extension/, with a path-derived identity.

After installing/selecting a supported channel, run:

herdr-mcp native-host status

Require the active channel, extension identity, and Native Host runtime generation to match the intended installation. Do not use DEV as the ordinary-user fallback, and do not call a GitHub/manual fixed-identity package "dev".

See Browser extension and Browser Control Center.

What “installed” means#

At minimum:

herdr --version works;
herdr-mcp doctor is healthy;
Herdr Link is connected;
Edge /health is reachable;
ChatGPT OAuth is complete;
a new conversation can call herdr_inspect against the real workstation;
if the optional extension is installed, herdr-mcp native-host status is healthy and Control Center can see workspaces.

Automated execution entry point#

For automated installation, the Agent reads Agent install directly. Use Agent installation when the full permissions, security, and failure-boundary contract is needed.

Read deeper only when needed:

Maintainer UAT, GA gates, and release evidence are intentionally outside the normal user installation flow.

Repair, reinstall, and uninstall#

Use the product-level lifecycle commands rather than manually deleting launchd files or runtime directories:

herdr-mcp reinstall
herdr-mcp uninstall

On macOS, reinstall repairs/replaces the managed Rust runtime while retaining configuration and credentials. On Linux, use herdr-mcp install for runtime repair and herdr-mcp service uninstall for explicit service removal; full product uninstall remains a macOS lifecycle integration. On macOS, generations follow normal service GC, preserving the active/rollback-safe set. uninstall removes strongly owned local herdr-mcp runtime/config state. The default instance covers its service, owned daily auto-update scheduler, Link/watchdogs, Native Messaging host, managed CLI link, and config root; a named instance removes only its own service/watchdogs/config. Product uninstall arms a tiny durable update-fence tombstone under the user cache outside the config root before teardown, so a queued silent updater cannot resurrect the removed service after the config directory is gone. That tombstone is cleared only by an explicit successful install/reinstall. It intentionally preserves Herdr itself (herdr, the Herdr service/socket/config), as well as separately managed browser/Cloudflare/Keychain/TCC authorization state. Run these lifecycle mutations from an independent terminal, not from a managed herdr_exec session that depends on the service being changed.