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 updatewith 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:
- service/process lifecycle survives install, restart/login recovery and failed activation without adopting unrelated processes;
- credentials remain private and device-bound across reinstall/recovery;
- managed-root filesystem operations cover native path semantics, including platform-specific absolute/relative path behavior and any claimed UNC/network filesystem behavior;
- runtime/Link remain loopback/outbound-only at the workstation boundary;
initialize,tools/list, reconnect and a real read-only Web-AI → Edge → Link → workstation request pass;- required clean-machine CI runs for that OS, and physical UAT covers boundaries that hosted CI cannot prove;
- 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.