feat(remote-control): add hub-mediated remote workspaces

[Ingwannu]

Summary

• Add a Hub/Executor Remote Workspace flow: the Hub keeps Codex, Claude Code, and Pi credentials/session state, while a paired OCX-only computer owns the selected workspace and performs approved file and command operations locally.
• Add one-time pairing codes, device-scoped hashed tokens, outbound WebSocket connectivity, signed end-to-end encrypted session envelopes, explicit workspace-root approval, reconnect/resume handling, and bounded RPC/tool bridges.
• Harden every command-capable Executor boundary:
  • Linux: bubblewrap with an exact Bun-file mount, private namespaces, network-off default, cancellation ownership, and hardlink preflight.
  • Windows: capability-free AppContainer created suspended and attached to a kill-on-close Job Object before resume, temporary ACLs, a secret-free environment, and an inherited-handle allowlist.
  • macOS: file tools only. The official helper rejects both probe and direct run requests until OCX has a narrow way to revoke every descendant without importing broad Seatbelt system authority.
• Reject native helpers inside writable workspaces, revalidate the pinned helper and approved roots immediately before use, reject multi-link files, and bound command-root preflight to 250,000 entries.
• Rate-limit unauthenticated pairing by a hashed kernel-observed peer: the 10th failed code is blocked for the remaining fixed 10-minute window, state is capped at 1,024 sources, and spoofable forwarding/Tailscale identity headers do not select a bucket.
• Add the Remote Workspace dashboard, CLI commands, management API routes, packaging inputs, architecture/product decision records, and user documentation.

This is intentionally a reviewable foundation, not a production rollout. Interactive PTY streaming, a hosted central relay, signed Windows release artifacts, a safe macOS command-containment owner, and real three-computer acceptance remain outside this PR.

@lidge-jun This changes authentication, WebSocket admission, workflow, and native process-isolation boundaries. Please give the exact head an explicit security/architecture review before merge.

Verification

• Validated integration base: dev at 24c0409ae; exact PR head: ba6f822ca. Current dev advanced afterwards by two Codex Set test/documentation-only commits (1a5c9ab23), with no runtime-code delta.
• Full local suite with project-pinned Bun 1.4.0 and isolated temporary HOME, OPENCODEX_HOME, CODEX_HOME, and PASEO_HOME: 17,929 pass / 19 skip / 0 fail.
• Local typecheck and privacy scan passed.
• Focused GUI integration after the latest dev merge: 10 pass / 0 fail; GUI lint, i18n lint, and production build passed.
• Documentation build passed: 433 pages.
• Rust unit tests and formatting passed; Clippy with -D warnings passed for Linux, x86_64-apple-darwin, and x86_64-pc-windows-msvc.
• Exact-head GitHub-hosted confinement checks:
  • Linux production runner: workspace write, adjacent read/write denial, live loopback denial, hardlink refusal, exact Bun mount, and detached-process cancellation passed.
  • Windows AppContainer: existing nested workspace read/write, adjacent read/write denial, loopback denial, suspended-before-Job ordering, and bounded network probe passed.
  • macOS: official helper probe and direct run remain explicitly fail-closed, leaving file tools enabled without advertising workspace.exec.
• Exact-head cross-platform CI, service lifecycle, packaging smoke, React Doctor, PR hygiene, and target enforcement passed.
• The first exact-head macOS general-suite attempt hit one unrelated CL-07 inactivity timing assertion; the same-head failed-job rerun passed, as did the focused test locally and the same test on current dev.
• Protected local Codex/OpenCodex/Paseo runtime configuration modes, sizes, and SHA-256 hashes remained unchanged after validation.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Draft status is deliberate. Do not merge until another maintainer has completed the required security/architecture review; macOS command execution remains an explicitly documented follow-up rather than a weakened sandbox in this PR.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

✅ READY

• all PR quality gates passed.

Hygiene

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

리뷰 · 우선순위 68 / 80

설명

지금 dev(HEAD 974283269, package 2.43.0)에는 이미 Remote Hub가 있다. 그건 서브컴의 Codex/Claude 요청을 컴1 provider gateway로 보내고, 자격증명은 허브에만 두는 쪽이다(docs-site/.../remote-hub.md, src/remote/). 그런데 “컴3 브라우저에서 프롬프트를 치고, 실제 파일·명령은 컴2에서 돌린다”는 작업 공간 원격 실행은 아직 없다. 현재 dev의 src/에도 remote-control/ 디렉터리는 없다.

이 PR(초안, improved-remote-control, +~15k)은 그 구멍을 메우는 Hub / Executor Remote Workspace 기반이다. 한 줄로 말하면:

1. 컴1(Hub, runtimeRole === "hub")이 Codex·Claude Code·Pi 자격증명과 세션을 들고,
2. 컴2(OCX-only Executor)가 사용자가 승인한 workspace root에서만 파일/명령을 실행하고,
3. 브라우저(컴3)는 대시보드 #remote로 기기를 고른다.

페어링은 짧은 일회용 코드 → 기기 토큰(ocxrw_…) 교환이다. 허브는 토큰 해시만 저장하고, 에이전트 WebSocket(/remote-workspace/agent)은 Bearer로 한 번 인증한 뒤 프레임은 Ed25519 identity + ECDH(P-256) + AES-GCM 세션 암호로 묶는다(src/remote-control/crypto.ts). 허브에 가는 pair 요청에는 root 경로를 안 보내고 id/label만 보낸다. 실제 경로는 실행기 로컬에만 남는다.

명령 실행(workspace.exec)은 OS 감금이 산 증명한 뒤에만 광고한다. Linux는 bubblewrap(workspace-command-runner.ts), macOS/Windows는 digest-pin된 Rust helper(native/remote-workspace-helper, Seatbelt / AppContainer+Job). 헬퍼가 없거나 SHA가 바뀌거나 probe가 실패하면 파일 도구만 남기고 명령을 끈다. 작성자도 PTY 스트리밍·중앙 릴레이·공증 바이너리·진짜 3대 수락은 이번 PR 밖이라고 명시했다. types.ts/config.ts 대형 분할과 겹치는 모양은 아니다. 기존 Remote Hub를 대체하지 않고 옆에 새 면을 깐다.

다만 헤드 CI에서 native workspace helper (macos) / (windows) 가 이미 실패다. 초안 유지·메인테이너 보안 리뷰 요청과도 맞다. 지금 dev에 바로 넣는 덩어리가 아니다.

라인 단위 문제

.github/workflows/ci.yml native-workspace-helper - 이 PR 헤드에서 macOS·Windows confinement probe 잡이 둘 다 fail이다. 감금 광고의 전제인 exact-head 증거가 아직 없다.

.github/workflows/ci.yml matrix - Linux bubblewrap 경로는 hosted confinement 잡이 없다. mac/win만 cargo probe다. Linux도 “실행 가능”으로 광고하려면 별도 검증 레인이 비어 있다.

src/server/index.ts /remote-workspace/pair - Origin 거부·본문 한도·runtimeRole === "hub" 가드는 좋다. 그런데 공개(또는 hub-management) 데이터면 위에 페어링 시도 횟수/IP 스로틀은 안 보인다. 코드 엔트로피는 크지만, 실패 응답을 느슨하게 두면 스캔 소음이 커질 수 있다.

src/remote-control/ 전체 규모(~15k, 서버·GUI·Rust·docs·devlog 한 PR) - 초안 “foundation”으로 의도됐지만, 리뷰·되돌리기·부분 머지 단위가 한 덩어리다. 보안 경계(페어링·WS·샌드박스·런타임 브리지)가 한꺼번에 들어온다.

docs / 제품 이름 - 기존 Remote Hub와 Remote Workspace 이름이 비슷하다. 기여자·사용자가 “자격증명 허브”와 “원격 작업공간 실행기”를 섞을 여지가 있다(기획서에는 구분돼 있음).

메인테이너의 판단이 필요한 지점

• 이 foundation을 한 PR로 보안 리뷰할지, 페어링/암호·WS / 실행기·샌드박스 / GUI·docs 로 쪼개 리뷰할지.
• native helper CI(mac/win) 빨강을 머지 차단 조건으로 둘지(작성자 의도상 두는 게 맞음). Linux bwrap hosted probe를 같은 게이트에 넣을지.
• /remote-workspace/pair·agent를 지금처럼 데이터면(+ hub-management allowlist)에 둘지, 배포 문서에서 Tailscale Serve/비공개 노출 규칙을 Remote Hub만큼 강하게 고정할지.
• dogfood 기본값을 계속 초안·opt-in hub role로 둘지, 언제 “지원 기능”으로 승격할지(공증 바이너리·PTY·3대 수락 전후).
• 기존 Remote Hub 문서/GUI 네비와 Remote Workspace 네비를 어떻게 나란히 설명할지(혼동 방지).

너의 추천

머지하지 말고 초안 유지. 방향은 현재 dev에 없는 실제 제품 구멍(원격 workspace 실행)을 정확히 찌르고, 페어링·토큰 해시·Origin 거부·digest-pin·fail-closed exec 광고 같은 뼈대는 설득력 있다. 다만 (1) native confinement CI 그린, (2) 메인테이너 보안/아키텍처 리뷰(요청한 그대로), (3) 가능하면 리뷰 단위 분할 또는 최소한 보안 경계별 체크리스트 통과 전에는 dev에 넣지 말자. types/config 분할 때문에 닫을 PR은 아니다. 중복 PR도 아니다.

이 댓글은 grok-bot이 작성했습니다

[Ingwannu]

@lidge-jun Grok 리뷰에서 지적한 차단 사항을 기준으로 PR 헤드를 다시 방어하고 검증했습니다.

쉽게 정리하면:

1. Windows 명령 실행은 이제 프로세스를 멈춘 상태로 만든 뒤 Job Object에 먼저 넣고, 그 다음에만 실행합니다. 필요한 Windows 환경 변수는 workspace 안의 임시 경로로만 구성했고, 기존에 있던 중첩 프로젝트 파일의 읽기/수정까지 실제 AppContainer probe로 확인했습니다. 네트워크 차단 검사도 무한 대기하지 않도록 500ms로 제한했습니다.
2. Linux는 CI에서 bubblewrap을 실제 설치하고 production runner를 통과시킵니다. workspace 밖 읽기/쓰기, loopback, hardlink 별칭, 취소 후 detached process 생존, Bun 디렉터리 전체 노출을 모두 막는지 확인합니다.
3. macOS는 억지로 명령 실행을 켜지 않았습니다. process group을 벗어난 자식을 완전히 회수할 좁은 OS 경계가 아직 없고, Apple의 넓은 기본 Seatbelt profile을 가져오면 다른 host service 권한까지 열릴 수 있습니다. 그래서 공식 helper의 probe와 직접 run 요청을 둘 다 거부하고, 현재는 file tools만 광고하도록 fail-closed 했습니다.
4. 페어링 공격 방어는 forwarding/Tailscale 헤더를 믿지 않고 kernel이 본 peer만 사용합니다. 잘못된 코드 10번째부터 429, 10분 고정 창, 최대 1,024 source, 메모리에는 source 원문 대신 SHA-256만 남깁니다.
5. writable workspace 안의 native helper, multi-link 파일, command 전 hardlink 별칭을 모두 거부합니다. helper digest와 승인 root도 실행 직전에 다시 확인합니다.

검증 결과:

• 최신 검증 헤드 ba6f822ca
• 프로젝트 고정 Bun 1.4.0 전체 로컬 suite: 17,929 pass / 19 skip / 0 fail
• GUI 통합 10개 테스트, lint, i18n, build, TypeScript, privacy scan, docs 433 pages 통과
• Linux/Windows/macOS 전용 hosted 보안 잡 통과
• exact-head Cross-platform CI 최종 통과
• macOS 일반 suite 첫 시도에서 기존 CL-07 inactivity timing assertion 1개가 흔들렸지만, 같은 헤드 failed-job 재실행은 통과했습니다. 해당 focused test와 현재 dev의 같은 macOS CI도 통과했습니다.
• 실제 Codex/OpenCodex/Paseo 설정 5개는 mode/size/SHA-256 모두 변경되지 않았습니다.

검증 후 dev가 Codex Set 테스트/문서 전용 커밋 2개만 더 전진했으며 runtime code 차이는 없습니다. PR은 계속 Draft이고 병합하지 않았습니다. 보안/아키텍처 경계 변경이므로 이 exact head를 한 번 독립 리뷰해 주세요.