Remote Link

머신 링크는 SSH를 통해 OpenCodex Home 컴퓨터와 Child 컴퓨터를 연결합니다. Home이 SSH 터널을 통해 Child를 서비스하고, 두 컴퓨터는 각각 로컬 OpenCodex 서비스를 10100 포트에서 계속 실행합니다. 대시보드는 Child 전용 링크 키를 SSH로 전달하므로 토큰을 직접 입력하지 않습니다.

요구 사항

Home 컴퓨터에서 OpenSSH 키 로그인으로 Child 컴퓨터에 접속할 수 있어야 합니다.
자식이 시작하는 링크에서는 자식에서 OpenSSH 키 로그인으로 홈에 접속할 수 있어야 합니다(비밀번호 로그인은 지원하지 않음).
Child 컴퓨터에 OpenCodex 2.66.0 이상이 설치되어 있어야 합니다(자식이 시작하는 링크에서는 Home에도).
두 컴퓨터 모두 macOS 또는 Linux여야 합니다.
Home에서 Child를 추가하는 대시보드는 Home에서 직접 열거나 페어링된 Hub 세션을 사용해야 합니다. 현재 컴퓨터를 Child로 전환하려면 운영자가 페어링한 대시보드 세션이 필요하며, 자격 증명 없이 발급된 로컬 세션은 이 라우팅 변경을 확정할 수 없습니다.

비밀번호 SSH와 Windows는 현재 흐름에서 지원하지 않습니다. 링크는 어느 쪽에서든 시작할 수 있습니다. 아래 순서대로 Home에서 시작하거나, 이어지는 “이 컴퓨터를 Child로 연결하기” 절처럼 Child에서 시작합니다.

`#remote`에서 Child 추가하기

대시보드에서 #remote를 열고 Remote Link를 켭니다.
Home을 선택한 뒤 Continue를 누릅니다. SSH 호스트 목록이 열립니다.
SSH 후보에서 호스트를 선택하거나 SSH 설정의 alias를 입력합니다.
연결 테스트를 실행하고 표시된 호스트 지문을 연결하려는 컴퓨터의 지문과 비교합니다. 비교하면 SSH가 호스트를 신뢰하기 전에 잘못된 컴퓨터나 변경된 호스트 키를 발견할 수 있습니다.
지문을 확인한 뒤 Child를 연결합니다.

대시보드는 토큰 입력을 요구하지 않습니다. 먼저 호스트를 검사하며, 지문을 명시적으로 확인하기 전에는 링크를 적용하지 않습니다.

Child 추가 창은 Child가 SSH를 통해 이 Home의 공급자를 사용한다는 점과 위의 사전 요구 사항을 안내합니다. 별칭은 브라우저를 표시하는 컴퓨터가 아니라 OpenCodex를 실행하는 Home의 ~/.ssh/config에서 가져옵니다. 검색은 성공했지만 호스트가 없다면 아래와 같은 Host 항목을 추가하고 다시 검색하세요. 기존 별칭을 직접 입력할 수도 있으며, 별칭을 선택하거나 입력하면 연결 테스트가 활성화됩니다. 창에서 이 가이드도 열 수 있습니다.

Host devbox
  HostName devbox.example.com
  User you
  IdentityFile ~/.ssh/id_ed25519

검색에 실패하면 빈 목록이라고 표시하지 않고 불러오기 실패, 확인 가능한 원인과 재시도 버튼을 표시합니다. 연결 테스트의 구체적인 실패 원인과 정제된 SSH 힌트는 활성 창에만 표시하며 뒤쪽 페이지에 중복 표시하지 않습니다. 원인과 아래 SSH 진단 방법을 확인하고 다시 시도하세요. 다시 검색해도 입력한 별칭은 유지되지만 연결 전에 지문을 새로 확인해야 합니다.

이 컴퓨터를 Child로 연결하기

Home의 프로바이더를 사용할 컴퓨터에서 다음을 진행합니다.

대시보드에서 #remote를 열고 Remote Link를 켭니다.
Child를 선택합니다. SSH 호스트 목록이 열립니다.
Home의 SSH 호스트를 선택하고 연결 테스트를 실행한 뒤, 호스트 지문을 비교하고 확인합니다.
안내를 읽고 Connect as Child를 선택합니다.

연결하면 이 컴퓨터의 OpenCodex가 다시 시작됩니다. 이미 실행 중인 Codex 작업은 먼저 끝나고, 다시 시작되는 동안 최대 1분 정도 새 요청이 실패할 수 있습니다. 그 뒤 대시보드가 스스로 새로 고쳐지고 Child 링크를 보여 줍니다. Codex는 이 컴퓨터의 http://127.0.0.1:<port>/v1을 그대로 사용하며 토큰이나 환경 변수를 설정할 필요가 없습니다. 로컬 OpenCodex가 각 요청을 Home으로 전달하고, Home은 자신의 프로바이더와 계정으로 응답합니다.

Child에 이 컴퓨터를 먼저 페어링하라는 안내가 나오면, 이 컴퓨터에 설정된 IP 주소 형식의 HTTP 루프백 대시보드(예: http://127.0.0.1:<configured-port>)를 여세요. 로컬 페어링 양식은 페어링이 필요하고 대시보드와 API가 같은 루프백 출처를 사용할 때만 표시됩니다. 양식의 ocx gui pair --origin "http://127.0.0.1:<configured-port>" 명령을 복사해 이 컴퓨터의 터미널에서 실행한 뒤, 일회용 코드를 양식에 붙여 넣으세요. 양식에 표시된 정확한 출처를 사용해야 하며, 프로바이더 API 키나 관리자 토큰은 페어링 코드가 아닙니다. 페어링 누락과 설정된 포트의 불일치는 서로 다른 사유입니다.

Child 역할을 선택하려면 OpenCodex가 독립형 런타임으로 설정된 포트에서 실행 중이어야 합니다. Child는 정확히 그 포트에서 다시 시작하기 때문입니다. 대시보드가 설정된 포트에서 실행되고 있지 않다고 알리면, 먼저 그 포트에서 OpenCodex를 다시 시작하세요.

링크 상태

Connected는 SSH 터널이 준비되어 Child가 Home 링크를 사용할 수 있다는 뜻입니다.
Reconnecting은 터널을 다시 연결하는 중이라는 뜻입니다. 재시도 중에는 요청이 일시적으로 Retry-After와 함께 503을 반환할 수 있습니다. 자기 대시보드에서 연결한 Child에서는 요청이 먼저 터널이 돌아오기를 최대 15초 기다립니다.
Failed는 조치가 필요하다는 뜻입니다. SSH 인증, 확인한 호스트 키, 포워딩 또는 타임아웃 사유를 확인하세요. SSH 터널을 띄운 쪽이 절전, 장애, 재시작 뒤에도 스스로 다시 시도합니다. Home이 추가한 Child라면 Home이, 자기 대시보드에서 연결한 Child라면 Child가 시도합니다. 타임아웃이나 포워딩 오류 뒤에는 약 1분마다, 인증 오류 뒤에는 5분마다 시도합니다. 호스트 키가 바뀐 경우에는 다시 시도하지 않습니다. 바로 다시 연결하려면 Home 대시보드에서 Retry를 누르거나 Home에서 ocx link reconnect --link-id <id>를 실행하세요. OpenCodex를 재시작하지 않고 그 링크의 터널만 다시 띄웁니다.

링크가 실패해도 로컬 프로바이더로 조용히 전환하지 않습니다.

Child 제거하기

Child의 Disconnect를 선택하고 alias를 확인합니다. Home은 터널을 중지하고 해당 Child의 링크 키를 폐기한 뒤 저장된 링크 기록을 삭제합니다.

Home에서 Child의 연결 해제 명령을 실행할 수 없으면 Remove here only를 선택합니다. 그러면 이 컴퓨터의 터널, 키, 기록만 삭제됩니다. 그 다음 Child에 로그인하여 실행합니다.

ocx disconnect

자식 연결을 끊으려면 자식에서 ocx disconnect를 실행합니다. 이 명령은 클라이언트 터널을 끊고 SSH를 통해 홈에서 링크를 폐기합니다. 홈에서 폐기하지 못하면 다음 문구를 출력합니다: Home revoke failed; run ocx link revoke --link-id <linkId> on the home.

보안

Child는 링크를 통해 Home 컴퓨터의 프로바이더와 프로바이더 인증 정보를 사용합니다. Home은 Child마다 별도의 링크 키를 만들며, 링크를 제거하면 그 키를 폐기합니다. 확인 전에 호스트 지문을 비교하여 잘못된 컴퓨터나 변경된 호스트 키를 실수로 허용하지 않도록 하세요. Tailscale identity로 발급된 대시보드 세션은 머신 링크를 관리할 수 없습니다. Child에서 키는 OpenCodex 안에만 머뭅니다. Codex나 Claude Code가 Child에서 보내는 인증 정보는 Home으로 전달되지 않으며, Child에서 127.0.0.1:<port>에 접근하는 프로그램은 키 없이 Home을 사용합니다. 이는 독립형 설치가 로컬 프로그램에 주는 것과 같은 신뢰 수준입니다. 다른 사이트의 웹 페이지는 거부됩니다.

CLI 레퍼런스

ocx link probe <alias> [--json]
ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]
ocx link port [--json]
ocx link issue --alias <alias> --tunnel-port <port> [--json]
ocx link status [--json]
ocx link revoke --link-id <id> [--json]
ocx link reconnect --link-id <id> [--json]

비대화형 실행(TTY 없음)에서는 --expect-fingerprint가 필수입니다. 대화형 터미널에서는 옵션을 생략할 수 있지만, 제시된 지문을 명시적으로 확인해야 합니다.

관련 가이드

단독 실행 환경의 페어링 승인

OpenCodex가 백그라운드 서비스로 실행 중이어도 기존 ocx gui pair --origin <로컬 주소> 명령을 사용할 수 있습니다. 서비스의 개인 OpenCodex 폴더를 소유한 계정으로 명령을 실행하고, 반환된 일회용 코드를 로컬 대시보드에 입력하세요. 서버 터미널, 추가 비밀번호, Windows Hello 또는 하드웨어 보안키가 필요하지 않습니다. CLI와 서버는 같은 최신 버전과 설정 폴더를 사용해야 하며, 업데이트 뒤에는 이전 서버를 재시작하세요. Hub 초대도 CLI와 서버의 버전이 다르면 함께 업데이트해야 합니다. 설정 폴더나 일회용 승인 폴더가 심볼릭 링크이면 페어링을 거부하므로, OPENCODEX_HOME에는 보호된 실제 폴더 경로를 지정하세요.

CLI는 짧게 유효한 일회용 승인 정보를 만들고, 사용하거나 실패하면 정리를 시도합니다. 실행 정보를 읽는 것만으로는 승인받을 수 없고, 검증에 필요한 원래 비밀값은 파일에 저장하지 않습니다. 이 방식은 개인 폴더의 쓰기 권한을 확인하는 것으로, 생체 인증이나 사람의 직접 승인을 증명하지는 않습니다. 사용자 파일을 자유롭게 수정할 수 있는 프로그램은 여전히 신뢰 범위 안에 있습니다. 기존 Hub 초대의 권한 정책은 바뀌지 않습니다. 페어링 요청이 실패하면 안내된 문제를 해결한 뒤 새 명령을 실행하세요. Windows의 SSH Remote Link 지원을 추가하는 변경은 아닙니다.

페어링 도중 프로세스가 중단되면 명령을 다시 실행해 새로운 승인을 받으세요. 서비스나 페어링 명령이 실행 중일 때는 페어링 상태 파일을 수동으로 제거하지 마세요.

Windows에서는 승인 폴더나 기록이 서버 실행 계정만 사용할 수 있도록 보호되지 않았거나, 소유자와 권한을 확인할 수 없으면 페어링을 거부합니다. 두 항목 모두 해당 계정이 소유해야 합니다. Administrators 그룹 소유는 이 그룹이 서버 실행 토큰의 기본 소유자이고 관리자 역할도 활성화된 경우에만 허용합니다. 권한 목록은 상위 항목의 권한을 상속하지 않도록 보호되어야 하며, 서버 실행 계정에 대한 일반적인 모든 권한 허용 항목을 포함해야 합니다. 그 밖에는 SYSTEM과 Administrators 그룹의 일반 허용 항목만 허용합니다. SYSTEM과 권한이 상승된 관리자는 이미 모든 파일의 소유권을 가져올 수 있고, 권한이 상승되지 않은 관리자는 이 항목으로 아무 권한도 얻지 못하기 때문입니다. 하위 항목으로의 상속은 폴더에만 허용합니다. 이 기준은 Windows가 보고하는 권한 목록에 적용되며, 같은 계정의 호환되는 중복 항목은 하나로 보고 아무 권한도 주지 않는 항목은 무시합니다. 거부된 기록은 그대로 두며 권한이나 소유자를 자동으로 수정하지 않습니다. 설정 폴더를 개인 전용으로 보호한 뒤 새 페어링 명령을 실행하세요.

이 검사는 승인 폴더와 기록에만 적용됩니다. 상위 폴더의 교체, 부모 폴더의 삭제 권한, 특권을 사용하는 복원 작업, 권한을 보호하기 전에 열린 핸들을 통한 접근까지 막지는 않습니다. 승인 정보가 일치하는 요청은 이후 폴더 권한 검사에서 거부되더라도 최대 5초로 제한된 검증 프로세스가 실행되는 동안 서버 처리를 막을 수 있습니다. 실행 파일 조회와 프로세스 시작 준비는 이 제한 시간이 시작되기 전에 이루어집니다. CLI 정리 과정에서 검증을 한 번 더 수행할 수도 있습니다. 검증 프로세스의 5초 제한은 명령의 10초 요청 제한 시간 안에 여유를 두지만, 검증이 느리면 페어링이 거부될 수 있습니다.

터미널에서도 ocx link probe <alias> --json으로 지문과 버전을 확인하고 ocx link add <alias> --expect-fingerprint SHA256:… --json으로 연결할 수 있습니다. 지문 옵션이 없으면 대화형 터미널에서 명시적으로 확인해야 합니다. Home은 Child의 재시작 지원과 curl을 먼저 확인한 뒤 연결하고 재시작하여 실제 릴레이를 검증합니다. 실패 후 Child 설정이 남았다는 안내가 나오면 Child에서 ocx disconnect와 ocx restart를 실행하세요. 자세한 조건은 영문 안내를 참조하세요.