herdr-mcpSource version v1.2.1
Operate & troubleshoot

Platform and compatibility support matrix

Production support is a tested security boundary, not a statement that a binary happens to start.

This page is the public 1.0 compatibility contract for Herdr-MCP. A platform is production-supported only when the table below says Production. Anything marked Candidate or Unsupported must not be presented as an equivalent production workstation target.

Protocol and runtime compatibility#

Herdr-MCP has several independent protocol layers. They intentionally do not share one version number.

Layer Current production identity Bounded compatibility Fail-closed rule
Public MCP client protocol 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07 are accepted by initialize negotiation ChatGPT/OpenAI discovery may advertise probe version 2026-07-28; that probe value is not an extra initialize protocol Missing or unrecognized initialize protocol values negotiate down to the explicit legacy baseline 2025-11-25; no unlisted protocol is advertised as supported
Public Edge tool contract epoch 7, 19 actions A client conversation may retain an older tool snapshot, but Edge publishes the current DEV/PROD public catalog; the epoch-3 identity remains only as the conservative non-DEV/PROD fallback and rollback baseline Tools outside the current public contract are rejected
Workstation Runtime Execution Contract epoch 4, 18 tools The immediately previous frozen epoch 3, 18 tools is accepted as the bounded rollback baseline, together with the frozen epoch 2, 18 tool catalog Any other epoch/hash pair is rejected before workstation execution
Relay wire protocol numeric protocol_version = 1 None Missing, string-valued, or unknown protocol versions are rejected before relay state is written
Durable runtime state Current binary schema; exactly one declared, irreversible forward step (N→N+1) is admitted through explicit herdr-mcp update with a state backup Older stores migrate forward transactionally through append-only migrations Downgrade, multi-step, or undeclared schema changes are refused; scheduled updates refuse migrations and a store newer than the running binary is fail-closed

The current ChatGPT path is tested as a stateless Streamable HTTP client: openai-mcp initialize and tools/list responses use the required SSE framing, notifications/initialized is accepted, and Connector reconnect does not depend on preserving an obsolete Mcp-Session-Id. Workstation reconnect, Durable Object rehydration, heartbeat hibernation, and reconnect grace are covered independently so a browser reconnect is not treated as proof that a workstation mutation is safe to replay.

Herdr runtime support#

herdr-mcp drives exactly one Herdr runtime: the Herdr TUI. Versions below were checked on 2026-10-30.

Herdr runtime herdr-mcp v1.1 status Notes
Herdr TUI (herdr CLI + herdr server) Supported The only runtime herdr-mcp drives: workspaces, tabs, panes and agents through the Herdr TUI socket API. CI and the release gate pin Herdr TUI 0.9.5. Documentation: Herdr TUI docs.
Herdr app (0.1.9) on herdr-core (hc 0.1.14) Unsupported A separate runtime with its own JSON-RPC/OpenRPC socket. It models terminals instead of workspaces/tabs, reports agent status only through OSC 7501, and does not share agents with the Herdr TUI. Agents started there are invisible to herdr-mcp.

N, N-1 and N+1 policy#

N means the currently deployed Edge contract and the currently qualified runtime generation.

  • N → N is the normal production path. Candidate activation checks health plus the exact runtime execution contract before traffic moves. Release update activation additionally requires the release manifest to match the local durable-state schema.
  • N-1 runtime execution is a bounded rollback path, not a general compatibility promise. Today that means the immediately previous frozen epoch-4 runtime contract, plus the frozen epoch-2 catalog still present in the field, remain accepted beside current epoch 5. The pair is validated by epoch and hash; arbitrary older catalogs are not accepted.
  • N+1 runtime or control plane is not guessed. A future epoch, relay protocol, or durable-state schema remains incompatible until the corresponding Edge/runtime migration is explicitly shipped and qualified. Current code rejects unknown contract pairs and future durable-state schemas instead of attempting a best-effort downgrade.
  • Durable state migration is one-way during upgrade. Exactly one declared, irreversible forward state-schema step (N→N+1) is admitted through explicit herdr-mcp update with a state backup. Downgrade, multi-step, and undeclared changes are refused; scheduled updates refuse migrations. Rollback restores the backup before an older binary is started. Runtime rollback changes execution ownership; it does not undo Git/files/service side effects already performed by a tool call.

A contract migration and an implementation update are separate operations. A patch may change runtime implementation without changing tools/list; adding/removing a model-visible tool requires an explicit contract epoch migration and client/tool-snapshot qualification.

Platform support#

Platform Status Filesystem boundary Process / credential boundary Network boundary Qualification notes
macOS (Apple Silicon) Production Remote file/Git mutation is restricted to live managed Git roots, with read-only/write-root, dirty/busy and secret-path gates. Shell execution remains the logged-in user's shell and is not a sandbox. TCC-sensitive native access uses the long-lived Herdr-MCP broker responsibility boundary. User launchd owns the managed runtime and production Link; immutable generations switch through runtime/current. Local browser IPC uses an owned mode-0600 Unix socket; device/runtime credentials use the macOS credential boundary. Runtime MCP stays on loopback behind a local bearer. The workstation opens the authenticated outbound Link to Edge; no inbound workstation listener is exposed publicly. Physically qualified. Apple Silicon macOS is the primary production path; TCC broker/process, generation rollback, OAuth/Connector, real ChatGPT and browser-extension paths have dedicated regression/UAT coverage.
Linux x86_64 (native Debian-class host) Production Same managed-Git-root and mutation gates as macOS, enforced with normal Unix filesystem ownership/permissions. There is no macOS TCC equivalent; shell remains the workstation user's unsandboxed shell. systemd --user is preferred; the managed current-user process backend is the qualified fallback when a user systemd manager is unavailable. Device credentials and owned service/control files use private per-user storage/permissions. The managed runtime binds the browser extension's mode-0600 extension.sock, and native-host install registers the Chromium host for Google Chrome (Chromium and Chrome for Testing when those config directories exist). Same loopback runtime + authenticated outbound Link model. The extension does not use the loopback bearer. Physically qualified. Native Debian existing-fleet installation, Link/service lifecycle and updater application have been qualified; the release artifact is static x86_64-unknown-linux-musl.
Linux ARM64 / aarch64 (native Debian-class host) Production Same Linux managed-root and Unix ownership boundary as x86_64. Same systemd --user / managed-process service model, private credential store, and Chromium Native Messaging host as Linux x86_64. Same loopback runtime + authenticated outbound Link model. The extension does not use the loopback bearer. Physically qualified on NanoPi R5C / Debian 11 ARM64. Exact-source release build, immutable-generation install, preserved enrolled device identity, systemd-user service/Link reconciliation and Edge herdr_inspect all passed. Release qualification also builds and smokes static aarch64-unknown-linux-musl on a native GitHub ARM64 runner.
Windows x86_64 Candidate — not production Physical-machine UAT has exercised the native managed-root/path boundary, but the 1.0 Production claim still requires the full #394 promotion record against the exact current-main candidate. The native implementation from #364 is on main and uses current-user processes, Windows Credential Manager and a Startup-folder login entry, with process ownership fencing. The 1.0 runtime also enables first-device worker bootstrap on Windows, including canonical enrollment and managed Link activation. Source merge and hosted CI are qualification evidence, not a production guarantee. Physical UAT exercised install/service/Link recovery, simulated-login recovery, preserved device/Connector state and a real Connector conversation; #514 fixed the Windows HOME/PATH defects exposed during qualification. Candidate follows the same loopback + authenticated outbound Link model. Physical x86_64 UAT has been exercised, but Production promotion remains open under #394. Before the final 1.0 claim is frozen, record one fresh Windows first-device worker bootstrap on the exact candidate through Worker creation, canonical enrollment, Link readiness, and a real MCP call. The remaining promotion record must also include preserved device/Connector identity, simulated-login recovery, final read-only inspect/workspace/pane access, and managed-root path evidence. UNC/network paths remain outside the support claim without an explicit fixture; UNC/path behavior must be covered before any broader filesystem claim.
Windows ARM64 / aarch64 Candidate — not production Same candidate filesystem/path contract as Windows x86_64; no physical-machine filesystem claim yet. Same native Windows current-user process, Credential Manager and Startup-folder ownership model. Same candidate loopback + authenticated outbound Link model. Native GitHub windows-11-arm release build/qualification tested; no physical Windows ARM64 UAT yet. The published target is aarch64-pc-windows-msvc; production promotion remains gated on physical-machine lifecycle, credential, path and end-to-end Link UAT.
WSL Unsupported No WSL host/guest filesystem, Windows-drive mount, symlink, or permission model has been qualified as equivalent to native Linux. No WSL-specific service manager, credential, browser IPC or host/guest process ownership boundary is claimed. WSL/NAT/Windows-host networking is not a qualified production Link boundary. A Linux binary starting inside WSL is not support evidence. Do not use WSL as a security-sensitive Herdr-MCP workstation target until a separate qualification explicitly defines these boundaries.

What “Production” does and does not mean#

Production support means the Herdr-MCP-owned boundary is explicit and tested. It does not turn the workstation into a container sandbox:

  • herdr_fs_* and managed Git operations are project-root gated;
  • herdr_exec* intentionally executes as the workstation user and can access whatever that user can access;
  • Herdr panes/agents are persistent local processes under that same workstation security model;
  • Edge OAuth, device authorization and outbound Link authentication protect remote entry; they do not reduce local user privileges.

When a platform cannot provide an equivalent boundary, the correct status is Candidate or Unsupported rather than silently weakening the contract.

Promotion checklist#

A Candidate platform may move to Production only after all of these are true on the exact implementation being merged:

  1. service/process lifecycle survives install, restart/login recovery and failed activation without adopting unrelated processes;
  2. credentials remain private and device-bound across reinstall/recovery;
  3. managed-root filesystem operations cover native path semantics, including platform-specific absolute/relative path behavior and any claimed UNC/network filesystem behavior;
  4. runtime/Link remain loopback/outbound-only at the workstation boundary;
  5. initialize, tools/list, reconnect and a real read-only Web-AI → Edge → Link → workstation request pass;
  6. required clean-machine CI runs for that OS, and physical UAT covers boundaries that hosted CI cannot prove;
  7. unsupported or unqualified sub-environments remain explicitly unsupported rather than inheriting a broader platform label.

Related reading: Architecture, Runtime upgrades, Troubleshooting, and the contributor release model.

Documentation

Search herdr-mcp docs

Type to search across all guides (supports English, Chinese, and Japanese queries).