Documentation problem type
Broken example or command
Documentation location
https://opencodex.me/guides/remote-hub/ — Linux systemd or macOS launchd and Tailscale Serve sections.
What is wrong or missing?
The setup example uses ocx config set hub.managementPublicOrigin ..., hub.managementIngress ..., and remoteGui.allowedTailscaleUsers ... on an existing standalone installation. When hub or remoteGui is absent, the CLI rejects a nested set with Error: config parent path not found: hub (or remoteGui). A fresh standalone configuration cannot follow the example verbatim.
This was observed during a Windows 2.50.0 client / macOS source-checkout hub setup. The hub was fast-forwarded to dev commit 6d3ad12 (2.51.0). No source modifications were needed to work around the configuration problem.
There is also a gap in the macOS transport instructions: the guide binds the data listener to the Tailscale IP, exposes only the management-only loopback ingress through Serve, and later uses an HTTPS URL for ocx connect. The management ingress explicitly cannot serve /readyz or /v1/*. The guide should show both the data URL and the separate --management-url, and how to provide TLS to the data listener on macOS. The Tailscale macOS extension refused a Serve target of http://<node-tailscale-ip>:10100 with its remote-destination limitation. This is an external platform constraint, not necessarily an OpenCodex runtime defect.
What should the documentation explain instead?
Initialize missing object sections before setting their fields, or use whole-object examples. Explain preserving existing object fields when adapting an existing config. Clearly distinguish the data listener, the management ingress, and their external HTTPS origins. Provide a supported macOS Tailscale-extension data transport example, including authenticated transport and readiness/catalog validation.
Suggested wording or example
For a configuration without either object:
ocx config set runtimeRole hub
ocx config set hub '{"managementPublicOrigin":"https://hub.example.ts.net","managementIngress":{"enabled":true,"port":10101}}'
ocx config set remoteGui '{"allowedTailscaleUsers":["operator@example.com"]}'For separate HTTPS frontends, explicitly document:
ocx connect https://hub.example.ts.net:8443 --management-url https://hub.example.ts.net --admin-token-stdin
The example assumes that the operator has established working authenticated TLS transport for the data listener on 8443; merely forwarding the management ingress is insufficient. Do not suggest disabling certificate validation or fabricating identity headers.
Additional context or attachments
The deployment succeeded using whole-object config initialization, a Tailscale-IP-bound authenticated data listener, and a loopback-only TCP bridge for the macOS Serve backend. Authenticated catalog retrieval and one streamed model response succeeded. No credentials, host-specific addresses, or account details are included here.
Checks
Documentation problem type
Broken example or command
Documentation location
https://opencodex.me/guides/remote-hub/ — Linux systemd or macOS launchd and Tailscale Serve sections.
What is wrong or missing?
The setup example uses
ocx config set hub.managementPublicOrigin ...,hub.managementIngress ..., andremoteGui.allowedTailscaleUsers ...on an existing standalone installation. WhenhuborremoteGuiis absent, the CLI rejects a nested set withError: config parent path not found: hub(or remoteGui). A fresh standalone configuration cannot follow the example verbatim.This was observed during a Windows 2.50.0 client / macOS source-checkout hub setup. The hub was fast-forwarded to dev commit 6d3ad12 (2.51.0). No source modifications were needed to work around the configuration problem.
There is also a gap in the macOS transport instructions: the guide binds the data listener to the Tailscale IP, exposes only the management-only loopback ingress through Serve, and later uses an HTTPS URL for
ocx connect. The management ingress explicitly cannot serve/readyzor/v1/*. The guide should show both the data URL and the separate--management-url, and how to provide TLS to the data listener on macOS. The Tailscale macOS extension refused a Serve target ofhttp://<node-tailscale-ip>:10100with its remote-destination limitation. This is an external platform constraint, not necessarily an OpenCodex runtime defect.What should the documentation explain instead?
Initialize missing object sections before setting their fields, or use whole-object examples. Explain preserving existing object fields when adapting an existing config. Clearly distinguish the data listener, the management ingress, and their external HTTPS origins. Provide a supported macOS Tailscale-extension data transport example, including authenticated transport and readiness/catalog validation.
Suggested wording or example
For a configuration without either object:
For separate HTTPS frontends, explicitly document:
The example assumes that the operator has established working authenticated TLS transport for the data listener on 8443; merely forwarding the management ingress is insufficient. Do not suggest disabling certificate validation or fabricating identity headers.
Additional context or attachments
The deployment succeeded using whole-object config initialization, a Tailscale-IP-bound authenticated data listener, and a loopback-only TCP bridge for the macOS Serve backend. Authenticated catalog retrieval and one streamed model response succeeded. No credentials, host-specific addresses, or account details are included here.
Checks