Fleet ops and gateway

Preview docs describe unreleased preview builds. Stable docs remain at /docs/.

CHEF fleet tooling adds optional what runs where context on top of Herdr’s normal session server. Herdr stays the runtime owner; plugins and the gateway expose neutral location facts for operators and phone clients.

Fleet Ops Bar

When enabled, Herdr renders a compact bar under pane borders with fleet context from linked plugins. Toggle it in Settings → Plugins with ui.fleet_ops_bar = true in config.

The bar reads merged plugin state from $HERDR_PLUGIN_STATE_DIR/fleet_ops.json. It is presentation-only: no secrets, no write-back into Herdr core state.

fleet_ops.json contract

Plugins under com.chefgroep.* write JSON fragments into $HERDR_PLUGIN_STATE_DIR/fleet_ops.json. Herdr merges fragments from all linked fleet plugins and refreshes the bar on a short TTL.

Keep fragments small and safe to display:

host or fleet summary strings
online/total counts
links or labels that do not embed credentials

Linear remains the work-item source of truth; GitHub for PR/CI; host and Cloudflare APIs for runtime health. Do not store API tokens or private keys in fleet_ops.json.

Link a local scaffold and invoke actions:

herdr plugin link ./plugins/ops
herdr plugin action invoke publish-context --plugin com.chefgroep.ops

Ops plugins

Piece	Role
`com.chefgroep.ops` (in-repo scaffold)	Documents the contract and exercises the plugin path in free CI
GroepOnline/herdr-ops	Production inventory, Tailscale/host probes, and SSOT plugins

The in-tree scaffold publishes a minimal host/socket summary. Production inventory and health checks belong in herdr-ops; link or install those plugins the same way as any other Herdr plugin.

See Plugins for manifest fields and action wiring.

Host identity

Set a stable host label when many machines run Herdr:

export HERDR_HOST_NAME=build-01

Herdr, fleet plugins, and the gateway fall back to HOSTNAME or the OS hostname when HERDR_HOST_NAME is unset. Prefer unique values across a fleet so phone attach and ops dashboards do not collapse distinct hosts.

herdr-gateway

herdr-gateway is a small HTTP adapter in front of the local Herdr socket. It does not replace the socket API; it exposes a few read-only JSON routes for scripts, fleet tooling, and Moshi-style remote clients.

Run it on the host where the Herdr server already runs:

herdr-gateway
# listens on http://127.0.0.1:7777 by default

Environment:

Variable	Default	Purpose
`HERDR_GATEWAY_PORT`	`7777`	TCP listen port
`HERDR_SOCKET_PATH`	`~/.config/herdr/herdr.sock`	Herdr server socket

Use SSH port forwarding or Tailscale serve when you need remote access; the gateway binds to localhost by default.

HTTP routes

Route	Description
`GET /health`	Gateway uptime, socket path, host name
`GET /v1/ops/context`	Host + socket + `agent.list` + `session.snapshot`
`GET /v1/agents`	Proxy to `agent.list`
`GET /v1/workspaces`	Proxy to `workspace.list`
`GET /v1/session`	Proxy to `session.snapshot`
`GET /v1/events`	SSE stream from `events.subscribe`

Example:

curl -s http://127.0.0.1:7777/v1/ops/context | jq .

/v1/ops/context is the neutral runtime location surface: host identity, socket path, live agents, and session shape. Inventory SSOT plugins in herdr-ops should consume this endpoint (or the socket API directly) instead of adding private TUI-only fields.

Mobile and remote attach

For iPhone access, keep Herdr on the host and attach over SSH or mosh. See Moshi (iPhone) with Herdr for the recommended stack. Use /v1/ops/context or the Fleet Ops Bar to pick the right host before connecting from a phone.