RepoRelay

RepoRelay의 기능

RepoRelay는 로컬의 자체 MCP 브리지로, ChatGPT에게 컴퓨터의 정확히 하나의 승인된 저장소에 대한 제한된 접근 권한을 부여합니다 — 그 이상은 없습니다.

ChatGPT는 RepoRelay를 통해 코드를 검토하고, 고정된 핸드오프 파일을 통해 별도의 로컬 코딩 에이전트(예: Codex 또는 Claude)를 위한 구조화된 작업을 남길 수 있습니다. RepoRelay는 ChatGPT와 사용자 컴퓨터 사이의 보안 경계입니다.

ChatGPT reviews/plans
        ↓
RepoRelay
        ↓
Repository reads/searches
+
fixed .ai-handoff writers
        ↓
Codex / another local coding agent implements

Related MCP server: codex-web-bridge

안전 모델의 작동 방식

MCP(Model Context Protocol)는 ChatGPT가 도구를 호출할 수 있게 하는 표준입니다. ChatGPT는 MCP 클라이언트입니다. RepoRelay는 로컬 MCP 서버이자 보안 경계로, ChatGPT가 무엇에 접근할 수 있는지 결정하고 한 번에 정확히 하나의 승인된 저장소만 노출합니다. tunnel-client는 ChatGPT 트래픽을 사용자 컴퓨터로 전달하는 안전한 네트워킹 파이프일 뿐입니다.

ChatGPT가 RepoRelay를 통해 할 수 있는 작업 (일반적인 7개 도구 설정):

✓ inspect files          open_workspace, list_files, read_file
✓ search the repository  search_files
✓ write to three predetermined handoff targets
                         write_next_task, write_review, update_handoff_state

ChatGPT가 할 수 없는 작업:

✗ run shell commands
✗ run PowerShell
✗ run Git
✗ launch processes
✗ arbitrarily edit source files
✗ delete files
✗ choose arbitrary write targets
✗ access outside the approved repository

이것이 RepoRelay의 가장 강력한 차별점 중 하나입니다: ChatGPT는 코드를 읽고 계획을 세울 수 있지만, 실행 능력은 전혀 없으며 사용자가 제어하는 몇 개의 고정된 핸드오프 파일에만 쓸 수 있습니다.

설치 전 확인 사항

다음이 필요합니다:

• Node.js >=22.19 및 <27 (npm 포함). node --version으로 확인하세요.

• ChatGPT가 검토할 기존 로컬 프로젝트 또는 저장소가 있어야 합니다. 컴퓨터의 실제 폴더여야 하며, 드라이브 루트나 전체 사용자 폴더가 아니어야 합니다.

• OpenAI Secure MCP Tunnel 접근 권한. RepoRelay는 OpenAI의 Secure MCP Tunnel을 통해 ChatGPT에 연결됩니다. 가용성, 권한 및 요금제 세부 사항은 현재 OpenAI Secure MCP Tunnel 가이드를 참조하세요.

• 대상 ChatGPT 워크스페이스에서 사용자 정의 MCP 앱을 생성/사용할 수 있는 권한 (ChatGPT 개발자 모드).

다른 것을 다운로드할 필요는 없습니다. RepoRelay는 reporelay tunnel setup 중에 공식 OpenAI tunnel-client를 자동으로 설치합니다.

핸드오프 프로토콜에 대해 아직 걱정하지 마세요. 빠른 시작에서 작동하는 핸드오프 파일을 설정하고 진행하면서 설명합니다.

빠른 설정

Windows 경로. 항상 전체 경로를 따옴표로 묶고 백슬래시를 유지하세요:

reporelay quickstart "C:\Users\you\Projects\my-app"

C:\Users\you\Projects\my-app이 올바릅니다. C:Users\you\Projects\my-app은 올바르지 않습니다 — 백슬래시가 중요합니다.

1. RepoRelay 설치

npm install -g reporelay-mcp@latest

설치 확인:

reporelay --version

reporelay가 인식되지 않으면 문제 해결을 참조하세요.

2. 하나의 저장소에서 RepoRelay 시작

reporelay quickstart "C:\Projects\my-app"

경로를 노출하려는 저장소로 바꾸세요. 이 PowerShell 창을 열어 두세요.

다음과 같은 메시지가 표시되어야 합니다:

Ready.
Local MCP: http://127.0.0.1:7676/mcp

일반적인 빠른 시작은 7개 도구 핸드오프 표면 (4개 검사 도구 + 3개 고정 핸드오프 작성기)을 활성화합니다. 이제 RepoRelay는 작은 .ai-handoff 워크스페이스와 AGENTS.md 노트를 생성하여 ChatGPT가 별도의 로컬 코딩 에이전트를 위해 구조화된 작업과 리뷰를 남길 수 있도록 합니다:

.ai-handoff/NEXT_TASK.md
.ai-handoff/REVIEW.md
.ai-handoff/RESULT.md
.ai-handoff/STATE.json
AGENTS.md

RepoRelay가 이것들을 생성하는 이유는 무엇인가요? ChatGPT는 여전히 명령을 실행하거나, Git을 사용하거나, 저장소를 임의로 편집할 수 없습니다. 이 파일들은 단순히 ChatGPT가 작업을 남기고, 별도의 로컬 코딩 에이전트(사용자 컴퓨터에서 사용자 권한으로 실행)가 결과를 남길 수 있는 장소입니다. 자세한 내용은 아래 ChatGPT ↔ 코딩 에이전트 핸드오프를 참조하세요.

나중에 RepoRelay를 중지하려면 이 창에서 Ctrl+C를 누르세요. reporelay quickstart --stop 명령은 없습니다.

3. 감사 실행

빠른 시작 직후, RepoRelay의 실제 보안 경계를 확인하세요:

reporelay audit "C:\Projects\my-app"

다음과 같은 메시지가 표시되어야 합니다:

RESULT: PASS

감사는 자체 임시 루프백 리스너를 시작하고 실제 인증된 MCP 표면, 격리 검사 및 핸드오프 제한을 실행합니다. 저장소를 수정하지 않습니다. 이는 ChatGPT가 연결되기 전에 RepoRelay를 검증합니다.

4. RepoRelay 터널 설정 실행

두 번째 PowerShell 창에서 다음을 실행하세요:

reporelay tunnel setup

이 명령은 RepoRelay 설정 마법사를 시작합니다. 모든 작업을 자동으로 수행합니다:

✓ installs a RepoRelay-supported OpenAI tunnel-client
✓ verifies it (pinned version + official SHA-256)
✓ opens OpenAI tunnel setup
✓ asks for your tunnel ID
✓ opens OpenAI runtime-key setup
✓ securely stores the pasted key
✓ creates the tunnel profile
✓ tests the complete connection

두 가지만 제공하면 되며, 둘 다 OpenAI Platform에서 제공합니다:

1. Secure MCP Tunnel ID — 마법사가 브라우저에서 https://platform.openai.com/settings/organization/tunnels를 엽니다. 터널을 생성하거나 선택하고, ChatGPT 워크스페이스와 연결한 후 tunnel_id를 터미널에 붙여넣으세요.

2. 런타임 API 키 — 마법사가 https://platform.openai.com/settings/organization/api-keys를 엽니다. 터널과 함께 사용하는 프로젝트의 시크릿 키를 생성하고 터미널에 붙여넣으세요. 입력이 숨겨집니다: 붙여넣는 동안 아무것도 표시되지 않습니다. 이 키는 tunnel-client를 OpenAI에 인증합니다. RepoRelay 브리지 시크릿이 아닙니다.

터널을 생성하거나 편집하려면 Tunnels Read + Manage 권한이 필요합니다. tunnel-client를 실행하거나 터널을 선택하려면 Tunnels Read + Use 권한이 필요합니다. 이는 조직 소유자 또는 RBAC 관리자가 부여하는 조직 수준 권한입니다. 정확한 UI 및 권한 세부 사항은 현재 OpenAI Secure MCP Tunnel 가이드를 따르세요.

마법사가 완료되면 다음 메시지가 표시되어야 합니다:

Testing connection...
✓ OpenAI runtime credential
✓ RepoRelay reachable
✓ Bridge authentication

Setup complete.

Next:
  reporelay tunnel run

이러한 검사는 실제로 이루어집니다: 설정은 런타임 API 키를 OpenAI 제어 평면( tunnel-client가 시작 시 수행하는 동일한 읽기 전용 터널 조회)에 대해 검증하고, 브리지 시크릿을 실제 실행 중인 RepoRelay에 대해 확인합니다. 잘못되었거나 만료되었거나 잘못 붙여넣은 키는 tunnel run이 시작된 후가 아니라 여기서 명확한 메시지와 함께 포착됩니다.

RepoRelay가 사용자 지정 포트(예: --port 7677)에서 실행 중인 경우, 빠른 시작이 이미 라이브 엔드포인트를 기록했으며 설정이 자동으로 이를 따릅니다 — 추가 플래그가 필요하지 않습니다.

유용한 옵션:

• reporelay tunnel setup --no-open — 브라우저를 열지 않음 (헤드리스, SSH 또는 CI); URL은 계속 출력됩니다.

• reporelay tunnel setup --replace-tunnel — 새 터널 ID를 묻습니다.

• reporelay tunnel setup --replace-runtime-key — 새 런타임 API 키를 묻습니다.

• reporelay tunnel setup --tunnel-client-path "C:\custom\tunnel-client.exe" — 비정상 환경을 위한 고급 재정의; RepoRelay는 사용자 지정 바이너리를 확인하거나 관리하지 않습니다.

reporelay tunnel setup을 다시 실행하면 기존의 확인된 클라이언트, 터널 ID 및 저장된 키를 재사용하고, 다시 묻지 않고 연결을 다시 테스트합니다.

5. 터널 실행

reporelay tunnel run

이 창을 RepoRelay 빠른 시작 창과 함께 열어 두세요. 완료되면 Ctrl+C로 중지하세요.

연결이 더 이상 작동하지 않으면 reporelay tunnel doctor가 독립적인 문제 해결 명령으로 계속 사용 가능합니다 (모든 것이 정상이면 Ready.가 표시됨; --verbose를 추가하면 수정된 진단 정보가 표시됨).

6. ChatGPT 앱 생성

ChatGPT에서 현재 OpenAI 흐름을 사용하여 (ChatGPT 개발자 모드 및 MCP 앱 가이드 참조):

ChatGPT
→ Apps / developer features
→ create custom MCP app
→ connection: Tunnel
→ choose RepoRelay's tunnel
→ authentication: No authentication
→ Scan Tools
→ verify 7 tools
→ create/use the app
→ start a new chat

다음 순서를 따르세요:

1. 사용자 정의 MCP 앱을 생성합니다.

2. Tunnel 연결을 선택합니다.

3. RepoRelay/OpenAI Secure MCP Tunnel을 선택합니다.

4. ChatGPT가 인증을 요청하면 No authentication을 선택합니다.

5. 앱을 저장하거나 생성합니다.

6. Scan Tools를 실행합니다.

7. 예상되는 RepoRelay 도구가 나타나는지 확인합니다.

8. 새 채팅을 시작하고 RepoRelay 앱을 선택합니다.

인증: No authentication. RepoRelay는 이미 터널에서 사용하는 보호된 X-RepoRelay-Bridge-Secret을 통해 로컬 브리지를 인증합니다. OAuth 또는 다른 ChatGPT 측 인증 방법을 구성하지 마세요.

127.0.0.1, localhost, RepoRelay 브리지 시크릿 또는 OpenAI 런타임 API 키를 ChatGPT에 절대 붙여넣지 마세요. 터널 연결이 모든 네트워킹을 처리합니다.

7. 7개의 RepoRelay 도구 스캔 및 확인

ChatGPT 앱 흐름에서 Scan Tools를 실행하고 RepoRelay가 정확히 다음 7개의 도구를 노출하는지 확인하세요:

open_workspace
list_files
read_file
search_files
write_next_task
write_review
update_handoff_state

이것이 예상되는 정상 표면입니다. Scan Tools에 셸, Git, 프로세스 실행, 일반 파일 편집, 삭제, 패치 또는 기타 예상치 못한 기능이 표시되면 앱을 사용하기 전에 중지하고 조사하세요 — reporelay audit "C:\Projects\my-app" --json을 실행하고 도구 목록을 확인하세요.

8. 테스트

새 채팅을 시작하고 RepoRelay 앱을 선택한 후 다음을 시도하세요:

Open the approved repository and list its top-level files.

그런 다음 경계를 테스트하세요:

Try to read .env.

두 번째 요청은 차단되어야 합니다.

연결되었습니다 — 이제 무엇을 할까요?

이제 ChatGPT가 검증된 보안 경계를 통해 저장소를 검토하고 있습니다. 유용한 프롬프트:

Read README.md and explain how this project starts.

Search the repository for "authentication".

Review src/server.ts for error-handling issues and write your findings.

ChatGPT ↔ 코딩 에이전트 핸드오프

일반적인 RepoRelay 설정을 통해 ChatGPT는 계획을 세우고 검토하는 동안 별도의 로컬 코딩 에이전트(Codex, Claude 또는 다른 것)가 구현을 수행합니다. RepoRelay는 작은 .ai-handoff 워크스페이스를 통해 이들을 조정합니다:

.ai-handoff/
├── NEXT_TASK.md   ChatGPT writes the task here
├── RESULT.md      the local coding agent writes its result here
├── REVIEW.md      ChatGPT writes its review here
└── STATE.json     coordinates the cycle

개념적으로:

ChatGPT
  ↓ writes NEXT_TASK.md

Codex / local coding agent
  ↓ implements
  ↓ writes RESULT.md

ChatGPT
  ↓ reviews result
  ↓ writes REVIEW.md

STATE.json이 주기를 조정합니다. RepoRelay 자체는 Codex 또는 Claude를 실행하지 않습니다 — 이들은 사용자가 직접 시작하는 별도의 로컬 애플리케이션입니다. 핸드오프 파일은 단순히 작업을 주고받기 위한 구조화된 장소입니다.

ChatGPT는 NEXT_TASK.md, REVIEW.md 및 STATE.json만 쓸 수 있습니다. 구현자가 소유한 RESULT.md는 ChatGPT가 절대 쓸 수 없습니다.

상세 프로토콜은 docs/handoff-cycle.md를 참조하고 리뷰어 및 구현자 프롬프트는 examples/를 참조하세요.

매일 사용하기

일회성 설정 후에는 터널이나 ChatGPT 앱을 다시 만들지 마세요. 매일:

1. RepoRelay를 시작합니다:

   reporelay quickstart "C:\Projects\my-app"

2. 터널을 시작합니다 (두 번째 창에서):

   reporelay tunnel run

3. ChatGPT를 열고 새 채팅을 시작한 후 기존 RepoRelay 앱을 선택합니다.

앱을 사용하는 동안 두 창을 모두 열어 두세요. 연결이 작동하지 않으면, reporelay tunnel doctor를 다시 실행하세요.

저장소 전환

RepoRelay는 한 번에 하나의 저장소만 노출합니다.

1. RepoRelay 터미널에서 Ctrl+C를 누릅니다.

2. 새 저장소에 대해 RepoRelay를 시작합니다:

   reporelay quickstart "C:\Projects\another-repo"

3. tunnel-client를 계속 실행하세요. 다시 시작된 RepoRelay에 자동으로 다시 연결됩니다(동일한 포트와 보호된 bridge-secret 파일). 다른 포트를 사용했다면 관리형 터널이 자동으로 해당 포트를 따라갑니다.

4. 새 ChatGPT 대화를 시작하고 RepoRelay 앱을 선택합니다.

5. ChatGPT에 새 저장소를 열도록 요청합니다.

승인된 저장소가 변경되었다고 해서 도구를 다시 스캔하지 마세요. 도구 정의가 변경되었거나 ChatGPT가 요청하는 경우에만 다시 스캔하세요.

문제 해결

다른 모든 경우에는 reporelay doctor를 실행하세요. 비밀 값은 출력하지 않고 구성 및 보안 상태를 출력합니다.

선택적 읽기 전용 모드

일반적인 RepoRelay 경험은 위의 7-도구 핸드오프 표면이며, 초보자에게 권장되는 설정입니다. ChatGPT가 검사만 수행하도록 하려면(핸드오프 파일 없음, 쓰기 작업 전혀 없음) 다음으로 시작하세요:

reporelay quickstart "C:\Projects\my-app" --no-handoff-writes

이 선택적 모드에서 RepoRelay는 정확히 네 가지 도구를 노출합니다:

open_workspace
list_files
read_file
search_files

읽기 전용 모드는 .ai-handoff를 생성하지 않으며, AGENTS.md를 생성하거나 수정하지 않고, 승인된 저장소를 변경하지 않은 상태로 둡니다. 모든 격리, 인증 및 보안 검사는 계속 적용됩니다. 일치하는 감사 플래그를 사용하세요:

reporelay audit "C:\Projects\my-app" --no-handoff-writes

이 모드를 사용하면 Scan Tools에서 7개 대신 4개의 도구가 표시됩니다.

보안

RepoRelay의 적용 경계는 다음을 포함합니다:

• 루프백 전용 바인딩 및 인증 필요;

• 정확히 하나의 기존 표준 승인 루트;

• .env, VCS 메타데이터, 자격 증명 저장소 및 개인 키 형식을 포함한 민감한 경로 차단;

• 탐색, 절대 외부 루트 경로, 심볼릭 링크/정션/재분석 지점 이스케이프 및 하드 링크 우회 차단;

• 제한된 읽기, 검색, 결과 및 핸드오프 콘텐츠;

• 셸, PowerShell, Git, 프로세스, 일반 쓰기, 패치, 삭제, 아티팩트, 작업 트리, 스킬, 하위 에이전트 또는 로컬 에이전트 도구 없음;

• 핸드오프 쓰기는 세 개의 고정된 사전 존재 대상으로 제한됨.

RepoRelay는 최소 권한 애플리케이션 경계이며, 동일한 로컬 사용자로 이미 실행 중인 악성 소프트웨어에 대한 운영 체제 샌드박스가 아닙니다. 외부 Secure MCP Tunnel은 별도의 보안 경계이며 독립적으로 보호되어야 합니다. 승인된 저장소를 신중하게 선택하세요.

전체 보안 모델 및 reporelay audit 설명서는 SECURITY.md를 참조하세요.

고급 구성

대부분의 사용자는 이것들이 필요하지 않습니다. 필요할 때:

• Configuration — REPORELAY_* 환경 변수, 브리지 인증, 포트, 로깅 및 핸드오프 모드.

• ChatGPT Web 설정 세부 정보 — 전체 터널 및 앱 참조.

• Windows 운영 — 수명 주기 스크립트, 예약된 작업 및 관리형 Windows 설정.

• .env.example — 자리 표시자 구성 전용. 실제 브리지 비밀 또는 터널 자격 증명을 절대 넣지 마세요.

• 로컬 MCP 클라이언트 — MCP 클라이언트가 RepoRelay와 동일한 컴퓨터에서 실행되는 경우 터널이 필요하지 않습니다: 퀵스타트에서 출력된 로컬 MCP URL을 가리키고 보호된 파일에서 로드된 X-RepoRelay-Bridge-Secret 헤더를 보내세요.

비밀 값을 출력하지 않고 구성 및 보안 상태를 확인하려면:

reporelay doctor

요구 사항 및 플랫폼 지원

• Node.js >=22.19 <27 (npm 포함);

• 클론 기반 설치를 위한 Git — ZIP을 대신 다운로드하는 경우 선택 사항.

이 README의 퀵스타트는 Windows, macOS 및 Linux에서 작동합니다. Windows 10/11은 PowerShell 스크립트 및 터널 관리 실행서를 포함하여 완전히 검증된 수명 주기 및 운영 플랫폼입니다.

제한 사항

• 한 번에 하나의 승인된 저장소만 노출됩니다.

• RepoRelay는 운영 체제 샌드박스가 아닙니다.

• ChatGPT Web은 비공개 로컬 브리지에 도달하기 위해 외부 OpenAI Secure MCP Tunnel 인프라가 필요합니다.

• Windows는 완전히 검증된 수명 주기 플랫폼입니다. 다른 플랫폼은 동일한 PowerShell/터널 작업을 제공하지 않습니다.

• Codex, Claude 및 기타 코딩 에이전트는 별도의 로컬 애플리케이션이며 RepoRelay의 구성 요소가 아닙니다.

문서

• ChatGPT Web 설정

• 보안 모델

• Configuration

• Windows 운영

• 설정 노트

• 핸드오프 주기

• 핸드오프 예제

• 기여하기

라이선스 및 프로젝트 계보

RepoRelay는 MIT License 하에 출시됩니다. 프로젝트는 필수 업스트림 저작자 표시를 유지하며 Codex, Claude 또는 다른 구현자의 SDK나 런타임을 번들로 포함하지 않습니다.

개발

npm ci
npm run typecheck
npm test
npm run verify:release
npm audit --audit-level=low
npm pack --dry-run --json
git diff --check