Repository navigation
docs: remote hub setup fails on missing parent objects and lacks macOS data TLS example #4200
Description
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-stdinThe 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
- I searched existing documentation issues.
- No secrets or personal information are included.
Activity
lidge-jun commentedon Sep 10, 2026
리뷰 · 우선순위 62 / 80
이 이슈는 제품 버그 신고가 아니라, 공개 가이드
https://opencodex.me/guides/remote-hub/(저장소 원본은docs-site/src/content/docs/guides/remote-hub.md)가 말해 주는 대로 따라가면 새 standalone 설정에서 막히는 문서 결함이다. Linux systemd / macOS launchd 절은ocx config set runtimeRole hub다음에hub.managementPublicOrigin,hub.managementIngress,remoteGui.allowedTailscaleUsers처럼 점 경로(nested set) 를 바로 친다. 그런데 지금devHEAD6d3ad12e3(package.json 2.51.0)의src/cli/config-command.tssetPath는 부모 객체가 없으면Error: config parent path not found: hub(또는remoteGui)를 던진다. 즉 예제 문장이 현재 CLI 동작과 맞지 않는다.작성자가 확인한 우회는 이미 이슈에 적혀 있다. 부모가 없을 때는 필드 하나씩이 아니라 객체 전체를 한 번에 넣는다. 예:
ocx config set hub '{"managementPublicOrigin":"...","managementIngress":{...}}',ocx config set remoteGui '{"allowedTailscaleUsers":[...]}'. 기존 설정에hub/remoteGui가 이미 있으면 점 경로 set이 통하고, 없을 때만 깨진다. 그래서 “CLI가 잘못됐다”보다 “가이드가 빈 설정과 기존 설정을 구분하지 않는다”에 가깝다. 런타임 코드 수정 없이도 문서만으로 재현·해결이 가능하다는 점도 이슈 본문에 분명히 적혀 있다(허브는6d3ad12e3까지 ff, 소스 패치 없음).두 번째 구멍은 전송 계층이다. 가이드는 데이터 리스너를 Tailscale IP의
:10100에 두고, Serve로는 루프백 관리 인그레스(127.0.0.1:10101)만 HTTPS로 내보낸다. 문서 상단도 관리 인그레스는/readyz,/v1/*, WebSocket을 절대 안 준다고 못 박는다. 그런데 뒤에ocx connect예시는 관리 HTTPS origin 위주로 보이고, macOS Tailscale 확장이http://<tailscale-ip>:10100을 Serve 대상으로 거절하는 경우(원격 destination 제한)에 데이터면 TLS를 어떻게 붙일지가 없다. 이건 OpenCodex 런타임 결함이라기보다 플랫폼 제약 + 문서 공백이다. 작성자가 제안한ocx connect https://…:8443 --management-url https://…처럼 데이터 URL과 관리 URL을 분리해 적고, 인증된 데이터 TLS를 운영자가 따로 준비한다는 전제를 명시해야 가이드가 end-to-end로 닫힌다.지금
dev방향과도 잘 맞는다. remote hub·Docker Compose·호환성 매니페스트 쪽은 이미 HEAD에 있고(#3604 등), 2.50.0 열차는 문서 클로즈아웃(#4196)까지 끝난 상태다. 이 이슈는 그 위에 “설치 문서를 따라 하면 된다”는 약속을 깨는 작은 균열이다. types.ts/config.ts 분할 캠페인이나 제품 PR 리베이스와는 무관하고, 중복 이슈로 보일 만한 동일 제목도 당장 열려 있지 않다. 우선순위는 런타임 블로커보다 낮지만, 신규 hub 운영자가 첫날에 막히는 문서라 60대 초반으로 둔다.경로
docs-site/src/content/docs/guides/remote-hub.md(Linux systemd or macOS launchd, 대략ocx config set hub.*/remoteGui.*줄) - 부모가 없는 fresh config에서 점 경로 set이 실패한다. 객체 통째 set 또는 부모 초기화 순서를 먼저 보여 줘야 한다.경로
src/cli/config-command.tssetPath-config parent path not found는 현재 의도된 CLI 동작이다. 가이드가 이 동작을 모르는 척하면 안 된다. 자동으로 빈 객체를 만들어 주는 제품 변경은 이 이슈의 필수 범위가 아니다.경로 같은 가이드 Tailscale Serve /
ocx connect절 - 관리 Serve만으로는/readyz·/v1/catalog·스트리밍이 안 된다. 데이터 리스너용 HTTPS(또는 동등한 인증 전송)와--management-url분리를 macOS 제약과 함께 적어야 한다.경로 번역본
docs-site/src/content/docs/{ko,ja,zh-cn,zh-tw,fr,ru,tr}/guides/remote-hub.md- 영어 원문을 고치면 번역본도 같은 예제 버그를 물려받는다. 원문 수정 후 번역 동기화 범위를 정해야 한다.경로 Docker Compose 절의
config set hub.*예시 - 컨테이너 시드 config에hub가 있으면 통과하지만, standalone 절과 메시지가 어긋나면 같은 함정이다. 문서 전체에서 “부모 없음” 케이스를 한 규칙으로 맞출지 확인이 필요하다.메인테이너의 판단이 필요한 지점
ocx config set이 없는 부모를 빈 객체로 자동 생성하게 제품도 바꿀지.너의 추천
remote-hub.md에 (1) fresh config용 객체 통째ocx config set hub/remoteGui예시, (2) 기존 객체 필드 보존 주의, (3) 데이터 URL +--management-url분리와 macOS에서 Serve가 데이터 IP를 거절할 때의 운영자 TLS 경로를 추가하라.이 댓글은 grok-bot이 작성했습니다
docs(devlog): lock the L7 wordings for #4215 and #4200
docs(remote-hub): make the setup runnable on a fresh config and close…
docs(devlog): record the lidge-jun#4200 delivery and the loopback-bin…
docs(i18n): make the remote hub guide runnable in every locale
docs(i18n): make the remote hub guide runnable in every locale
docs(devlog): lock the L7 wordings for lidge-jun#4215 and lidge-jun#4200
docs(remote-hub): make the setup runnable on a fresh config and close…
docs(devlog): record the lidge-jun#4200 delivery and the loopback-bin…
docs(i18n): make the remote hub guide runnable in every locale