원격 작업 공간

SSH 머신 링크는 Remote Link를 참조하세요.

원격 작업 공간에서는 한 opencodex Hub가 코딩 에이전트를 실행하고 다른 컴퓨터가 프로젝트 파일, 명령, 테스트, 빌드 연산을 제공합니다. 휴대전화나 세 번째 컴퓨터에서도 Hub 대시보드로 세션을 제어할 수 있습니다.

Phone browser -> Computer 1 OCX Hub -> encrypted channel -> Computer 2 OCX Executor
                 Codex / Claude / Pi                       project and commands
                 logins and sessions                      no coding CLI login

Executor에는 opencodex만 필요합니다. Codex, Claude Code, Pi, ChatGPT 로그인, 프로바이더 API 키는 필요하지 않습니다. Executor가 Hub로 아웃바운드 WebSocket을 열기 때문에 공개 포트나 라우터 포트 포워딩도 필요하지 않습니다.

Hub 설정

컴퓨터 1이 모든 코딩 에이전트 로그인과 모델 세션을 소유합니다. 사용할 에이전트를 이 컴퓨터에 설치하고 로그인한 뒤 opencodex를 Hub로 실행하세요.

ocx config set runtimeRole hub
OCX_REMOTE_WORKSPACE_ENABLED=1 ocx start
ocx gui

OCX_REMOTE_WORKSPACE_ENABLED=1은 Hub 프로세스 자체에 설정하세요. 대시보드 명령에만 설정해도 이미 실행 중인 서비스에는 적용되지 않습니다. 명시적으로 활성화하지 않은 Hub는 작업 공간 키를 만들거나 코딩 에이전트 런타임을 검사하지 않고 비활성화 상태를 반환합니다.

휴대전화나 다른 컴퓨터에서 대시보드를 열 때는 인증된 HTTPS 배포를 사용하세요. 지원되는 관리 접속 경로와 Tailscale 패턴은 원격 Hub 배포를 참고하세요. 인증되지 않은 로컬 대시보드 포트를 공개하지 마세요.

Codex 원격 작업 공간은 현재 App Server 권한 프로필을 사용합니다. Hub에서 선택한 Codex 설정에 이전 sandbox_mode 또는 sandbox_workspace_write가 남아 있으면 약한 경계로 시작하는 대신 대시보드가 Codex를 사용 불가로 표시합니다. 기능을 사용하기 전에 해당 Codex 프로필을 이전하세요. 이전 샌드박스와 권한 프로필을 함께 설정하지 마세요.

Executor 페어링

Hub 대시보드에서 Remote Workspace를 엽니다.
Create pairing code를 선택합니다.
컴퓨터 2에서 공개할 프로젝트 디렉터리로 이동합니다.
해당 컴퓨터에 맞는 Linux / macOS terminal 또는 Windows PowerShell 명령을 복사합니다. 현재 디렉터리를 페어링하고 터미널에서 ocx remote-workspace agent 연결을 유지합니다.

같은 작업을 수동으로 하려면 다음을 실행하세요.

cd /path/to/project
printf '%s\n' 'ONE-TIME-CODE' | ocx remote-workspace pair 'https://your-hub.example' \
  --pairing-code-stdin --root "$PWD"
ocx remote-workspace agent

Windows PowerShell에서는 대시보드에 표시되는 명령을 사용하세요. 수동 명령은 다음과 같습니다.

$pairingCode = 'ONE-TIME-CODE'
$pairingCode | ocx remote-workspace pair 'https://your-hub.example' `
  --pairing-code-stdin --root (Get-Location).Path
if ($LASTEXITCODE -eq 0) { ocx remote-workspace agent }

현재 OCX Bun 실행 파일은 Linux 샌드박스에 읽기 전용 파일 하나로 자동 추가됩니다. 프로젝트에 시스템 경로 밖에 사용자 설치 도구 체인이 필요하다면 홈 디렉터리 전체를 노출하지 말고 명시적으로 페어링하세요.

printf '%s\n' 'ONE-TIME-CODE' | ocx remote-workspace pair 'https://your-hub.example' \
  --pairing-code-stdin --root "$PWD" \
  --toolchain-root "$HOME/.nvm/versions/node/v24/bin"

네이티브 헬퍼 소스는 검토할 수 있도록 패키지에 포함됩니다. 빌드해도 이번 변경에서 Windows나 macOS 명령이 활성화되지는 않습니다. --executor-helper는 검토된 헬퍼를 선택하는 옵션입니다. 바이너리가 존재하거나 경로가 설정되어 있다는 사실만으로 명령 지원이 입증되지는 않습니다.

일회용 코드는 명령줄 인수가 아니라 표준 입력에서 읽습니다. 페어링하면 로컬 기기 서명 키와 기기 범위 bearer 토큰이 만들어집니다. Hub는 그 해시만 저장하고 Executor의 실제 경로는 받지 않습니다. Ctrl+C로 포그라운드 에이전트를 멈추세요. 다시 실행하면 같은 기기로 재연결됩니다.

비밀 정보를 출력하지 않고 로컬 등록 상태를 확인하려면 다음을 실행하세요.

ocx remote-workspace status

원격 코딩 세션 시작

대시보드에서 다음을 고르세요.

온라인 컴퓨터
로컬에서 승인한 작업 공간 폴더 하나
Hub의 Codex, Claude Code 또는 Pi
접근 모드

Read only가 기본값이며 디렉터리 목록과 파일 읽기를 허용합니다. Executor가 명령 샌드박스 검사를 통과한 경우에만 쓰기 옵션이 Edit files and run commands로 표시됩니다. 그렇지 않으면 Edit files only로 표시됩니다. 대시보드는 모델과 로그인이 Hub에 남고 작업 공간 작업은 선택한 컴퓨터에서 실행된다는 점을 두 위치로 나누어 보여줍니다.

컴퓨터 1, 컴퓨터 3, 휴대전화의 Hub 대시보드에서 프롬프트를 보내세요. 세션이 다른 컴퓨터나 폴더로 조용히 바뀌지 않습니다. Executor 연결이 끊기면 세션은 Executor offline 상태가 되고 Hub 파일 시스템으로 대체하지 않습니다.

프롬프트를 보내면 수락 여부를 즉시 응답하고, 대시보드는 진행과 완료 상태를 폴링합니다. 수락 응답을 잃으면 초안은 제출 여부를 알 수 없다는 알림과 함께 남습니다. 다시 보내기 전에 세션 진행 상태를 확인하세요. 대시보드는 프롬프트를 자동 재시도하지 않습니다.

프롬프트 실행 중에도 Stop을 사용할 수 있습니다. Hub 코딩 에이전트의 현재 턴을 중단하고 활성 Executor 명령을 취소하며, 늦게 온 응답이 중지된 세션을 다시 열지 못하게 합니다.

재시작과 재연결 동작

Hub는 제한된 세션 메타데이터와 최근 이벤트의 작은 스냅샷을 저장합니다. Hub 재시작 뒤 완료되지 않은 세션은 원래 Executor를 기다립니다. 해당 기기가 다시 연결되면 다음 프롬프트가 원래 Codex 작업, Claude Code 세션 또는 Pi 세션 ID를 이어갑니다.

Claude Code는 첫 프롬프트가 완료된 뒤 영구 기록을 만듭니다. 새 Claude 세션에서 프롬프트가 하나도 완료되기 전에 Hub가 멈췄다면 이어갈 대화가 없으므로 새 세션을 시작하세요.

기능 매니페스트가 바뀌어도 기존 세션의 경계를 조용히 약화하지 않습니다. Executor의 명령 격리가 사라지거나 사용 가능한 도구가 바뀌면 새 세션을 시작하세요. 컴퓨터의 권한을 취소하면 소켓이 닫히고 해당 컴퓨터에 묶인 세션이 중지됩니다.

보안 경계

프로바이더 자격 증명과 코딩 에이전트 기록은 Hub에 남습니다.
Executor 개인 키, 기기 bearer 토큰, 실제 루트 경로는 소유자만 접근 가능한 OCX 상태에 남습니다.
페어링 코드 실패 횟수는 모든 리스너에서 커널이 관측한 상대별로 제한됩니다. 10분 동안 열 번 실패하면 일반적인 429와 Retry-After를 반환합니다. Hub에는 해당 출처 ID의 제한된 만료 해시만 남습니다. 직접 로컬 호출자가 ID 헤더를 위조할 수 있으므로 Tailscale Serve 사용자는 관리 리스너의 루프백 버킷을 공유합니다.
작업 세션마다 Ed25519 서명 임시 P-256 ECDH 핸드셰이크와 순서가 정해진 AES-256-GCM 메시지를 사용합니다.
양쪽이 현재 기능 매니페스트에 동의하기 전까지 소켓을 온라인으로 표시하지 않습니다.
재연결 때 로컬 샌드박스를 사용할 수 없으면 기능을 제거할 수 있지만, 페어링 때 기록한 허용 범위 밖의 기능은 추가하지 않습니다.
모든 요청은 모델 작업, 기기, 루트, 접근 모드, 기능 집합 하나에 묶입니다.
경로는 상대 경로로 정규화되고 제한됩니다. 심볼릭 링크, 정션, 상위 디렉터리로 빠져나가는 경로는 거부합니다. Windows 기기 이름, 대체 데이터 스트림, 끝에 점이나 공백이 붙은 별칭도 거부합니다.
Executor 작업은 직렬화하고 열린 파일의 ID를 다시 확인합니다. 원자적 교체 직전에 쓰기 해시도 다시 확인합니다. 승인한 루트를 교체하려면 다시 페어링해야 하고 도구 체인 루트는 명령마다 재검증합니다.
파일 읽기·쓰기는 하드 링크된 파일을 거부합니다. 명령을 실행하기 전에 OCX는 작업 공간 항목을 최대 250,000개 검사합니다. 디렉터리가 아닌 항목에 링크가 여러 개 있으면 명령 경로를 비활성화합니다. 경로 샌드박스만으로는 같은 inode의 다른 이름이 승인된 루트 밖에 있는지 알 수 없기 때문입니다.
Linux 명령은 쓰기 가능한 작업 공간 하나, 비워진 환경, 격리된 프로세스 네임스페이스, 읽기 전용 파일 하나로 추가된 현재 OCX Bun 실행 파일, 제한된 출력과 시간 초과, 기본적으로 비활성화된 네트워크를 갖춘 bubblewrap에서 실행됩니다. 전용 격리 테스트에는 명시적으로 설정된 호스팅 환경이 필요합니다. 일반 테스트 묶음이 통과해도 이 테스트가 실행되었다는 증거는 아닙니다.
macOS는 파일 도구만 표시합니다. 자손 프로세스가 setsid()를 호출하면 프로세스 그룹에 그 프로세스를 가둘 수 없습니다. 명령 하나를 시작하려고 광범위한 Apple Seatbelt 시스템 프로필을 가져오면 관련 없는 호스트 서비스 권한도 노출됩니다. 따라서 OCX가 범위가 좁고 취소 가능한 자손 격리 소유자를 갖출 때까지 네이티브 헬퍼는 검사와 직접 명령 요청을 모두 거부합니다.
Windows와 macOS의 네이티브 명령 요청은 안전하게 실패합니다. 직접 헬퍼 거부 테스트와 실제 명령 격리 증거는 구분해야 합니다. Windows 명령 수락 기능은 아직 열려 있습니다.
고정된 네이티브 헬퍼는 승인된 쓰기 가능 작업 공간 모두의 밖에 있어야 합니다. OCX는 명령 지원을 알리기 전과 각 명령 직전에 이를 확인해 작업 공간 코드가 다음 샌드박스를 집행할 바이너리를 교체하지 못하게 합니다.
세션을 중지하면 활성 Executor 명령을 취소하고 Hub 모델 프로세스와 루프백 도구 브리지를 정리합니다. Windows는 소유한 npm 래퍼의 프로세스 트리를 멈춰 Node 자식이 남지 않게 합니다. Linux와 macOS는 CLI가 정상 종료 대기 시간을 무시할 때만 강제로 중지합니다.

Hub는 코딩 에이전트를 실행하므로 프롬프트와 모델 출력을 의도적으로 봅니다. 종단 간 암호화는 Executor RPC 페이로드를 보호합니다. 페어링된 Hub는 인증된 WSS를 통해 승인된 루트를 선택할 권한을 신뢰받으며, 자신의 모델 대화를 볼 수 없는 것은 아닙니다.

현재 범위

원격 작업 공간은 자격 증명을 다른 컴퓨터로 복사하거나 동기화하지 않습니다. 원격 Hub 프로바이더 라우팅 및 향후 호스팅 연산 또는 Super Sync 제품과도 별개입니다. 프로덕션 릴리스에는 서명된 Windows 헬퍼 패키징, 정확한 바이너리에 대한 네이티브 CI 증거, 독립 유지관리자 검토, 실제 세 컴퓨터 수락 테스트가 여전히 필요합니다.

프롬프트 수락 API

POST /api/remote-workspace/sessions/:id/prompt는 수락된 세션 스냅샷과 함께 HTTP 202를 반환합니다. 세션 ID와 단조 증가하는 이벤트 시퀀스가 수락 스냅샷을 식별합니다. 202는 모델 턴 완료를 뜻하지 않습니다. 이후 이벤트와 최종 상태는 GET /api/remote-workspace/sessions를 폴링하세요. 턴이 활성 상태인 동안에는 재연결과 런타임 재개가 사용 중 상태로 남습니다. 수락 응답을 잃으면 수락 여부를 알 수 없으므로 클라이언트는 다시 제출할지 결정하기 전에 폴링해야 합니다.