Give AI access to your repository — not your machine.
RepoRelay lets ChatGPT safely inspect one local repository without giving it control of the rest of your computer.
ChatGPT → Secure MCP Tunnel → tunnel-client → RepoRelay → one approved repository
Read safe files · Search code · One approved repository · No shell · No Git · No arbitrary writes
Quick Setup · Use It · Handoff · Troubleshooting · Security
RepoRelay is a local, first-party MCP bridge that gives ChatGPT bounded access to exactly one approved repository on your computer — nothing more.
ChatGPT reviews your code through RepoRelay, and can leave a structured task for a separate local coding agent (like Codex or Claude) through fixed handoff files. RepoRelay is the security boundary between ChatGPT and your machine.
ChatGPT reviews/plans
↓
RepoRelay
↓
Repository reads/searches
+
fixed .ai-handoff writers
↓
Codex / another local coding agent implements
MCP (Model Context Protocol) is the standard that lets ChatGPT call tools.
ChatGPT is the MCP client. RepoRelay is the local MCP server and security
boundary: it decides what ChatGPT may access and exposes exactly one approved
repository at a time. tunnel-client
is only the secure networking pipe that carries ChatGPT traffic to your computer.
| Component | Job |
|---|---|
| ChatGPT | MCP client — chooses RepoRelay tools. |
| Secure MCP Tunnel | Carries traffic from ChatGPT to your computer. |
tunnel-client |
|
| Local network forwarder; points the tunnel at RepoRelay. | |
| RepoRelay | MCP server + security boundary; enforces authentication and allowed access. |
| Repository | The one directory ChatGPT is allowed to inspect. |
What ChatGPT can do through RepoRelay (the normal 7-tool setup):
✓ 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
What ChatGPT cannot do:
✗ run shell commands
✗ run PowerShell
✗ run Git
✗ launch processes
✗ arbitrarily edit source files
✗ delete files
✗ choose arbitrary write targets
✗ access outside the approved repository
This is one of RepoRelay's strongest differentiators: ChatGPT can read and plan against your code, but it gets no execution capability and can only write to a few fixed handoff files you control.
You need:
Node.js>=22.19
and<27
(npm is included). Check withnode --version
.An existing local project or repository you want ChatGPT to review. It must be a real folder on your computer — not a drive root and not your whole user folder.OpenAI Secure MCP Tunnel access. RepoRelay reaches ChatGPT through OpenAI's Secure MCP Tunnel. See the currentOpenAI Secure MCP Tunnel guidefor availability, permissions, and plan details.Permission to create/use a custom MCP app in the target ChatGPT workspace (ChatGPT developer mode).
You do not need to download anything else. RepoRelay installs the official
OpenAI tunnel-client
automatically during reporelay tunnel setup
.
Do not worry about the handoff protocol yet. The quickstart sets up working handoff files for you and explains them as you go.
Windows paths.Always quote the full path and keep the backslashes:
reporelay quickstart "C:\Users\you\Projects\my-app"
C:\Users\you\Projects\my-app
is correct.C:Users\you\Projects\my-app
is not — the backslashes matter.
npm install -g reporelay-mcp@latest
Check the install:
reporelay --version
If reporelay
is not recognized, see Troubleshooting.
reporelay quickstart "C:\Projects\my-app"
Replace the path with the repository you want to expose. Keep this PowerShell window open.
You should see:
Ready.
Local MCP: http://127.0.0.1:7676/mcp
The normal quickstart enables the 7-tool handoff surface (4 inspection
tools + 3 fixed handoff writers). RepoRelay now creates a small .ai-handoff
workspace and an AGENTS.md
note so ChatGPT can leave structured tasks and reviews for a separate local coding agent:
.ai-handoff/NEXT_TASK.md
.ai-handoff/REVIEW.md
.ai-handoff/RESULT.md
.ai-handoff/STATE.json
AGENTS.md
Why does RepoRelay create these? ChatGPT still cannot run commands, use Git, or arbitrarily edit your repository. These files are simply a place where ChatGPT can leave a task, and a separate local coding agent (running on your own machine, with your own permission) can leave its result. More below in ChatGPT ↔ coding-agent handoff.
To stop RepoRelay later, press Ctrl+C in this window. There is no
reporelay quickstart --stop
.
Immediately after quickstart, verify RepoRelay's actual security boundary:
reporelay audit "C:\Projects\my-app"
You should see:
RESULT: PASS
Audit starts its own temporary loopback listener and exercises the real authenticated MCP surface, containment checks, and handoff restrictions. It does not modify your repository. This validates RepoRelay before ChatGPT is connected.
In a second PowerShell window, run:
reporelay tunnel setup
This starts the RepoRelay setup wizard. It does everything for you:
✓ 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
You provide exactly two things, both in OpenAI Platform:
Your Secure MCP Tunnel ID— the wizard openshttps://platform.openai.com/settings/organization/tunnelsin your browser. Create or select a tunnel, associate it with your ChatGPT workspace, and paste itstunnel_id
back in the terminal.A runtime API key— the wizard openshttps://platform.openai.com/settings/organization/api-keys. Create a secret key for the project you use with the tunnel and paste it in the terminal. Input is hidden: nothing appears while you paste. This key authenticatestunnel-client
to OpenAI; it isnot the RepoRelay bridge secret.
Creating or editing a tunnel needs the Tunnels Read + Manage permission;
running tunnel-client
or selecting the tunnel needs Tunnels Read + Use. These are organization-level permissions granted by your org owner or RBAC admin. Follow the current OpenAI Secure MCP Tunnel guide for the exact UI and permission details.
When the wizard finishes, you should see:
Testing connection...
✓ OpenAI runtime credential
✓ RepoRelay reachable
✓ Bridge authentication
Setup complete.
Next:
reporelay tunnel run
These checks are genuine: setup validates the runtime API key against the
OpenAI control plane (the same read-only tunnel lookup tunnel-client
performs
at startup) and verifies the bridge secret against the RepoRelay that is
actually running. A wrong, expired, or mis-pasted key is caught here with a
clear message — not after tunnel run
starts.
If your RepoRelay runs on a custom port (for example --port 7677
), quickstart already recorded the live endpoint and setup follows it automatically — no extra flags needed.
Useful options:
reporelay tunnel setup --no-open
— do not launch the browser (headless, SSH, or CI); the URLs are still printed.reporelay tunnel setup --replace-tunnel
— prompt for a new tunnel ID.reporelay tunnel setup --replace-runtime-key
— prompt for a new runtime API key.reporelay tunnel setup --tunnel-client-path "C:\custom\tunnel-client.exe"
—advanced override for unusual environments; RepoRelay does not verify or manage a custom binary.
Re-running reporelay tunnel setup
reuses your existing verified client, tunnel ID, and stored key, and re-tests the connection without asking for anything again.
reporelay tunnel run
Keep this window open alongside the RepoRelay quickstart window. Stop it with Ctrl+C when you are done.
If the connection ever stops working, reporelay tunnel doctor
remains
available as a standalone troubleshooting command (expect Ready.
when
everything is healthy; add --verbose
for redacted diagnostics).
In ChatGPT, using the current OpenAI flow (see the ChatGPT developer-mode and MCP apps guide):
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
Follow this sequence:
- Create the custom MCP app.
- Choose the Tunnel connection. - Select the RepoRelay/OpenAI Secure MCP Tunnel.
- When ChatGPT asks for authentication, select No authentication. - Save or create the app.
- Run Scan Tools. - Verify the expected RepoRelay tools appear.
- Start a new chat and select the RepoRelay app.
Authentication: No authentication.RepoRelay already authenticates the local bridge through the protectedX-RepoRelay-Bridge-Secret
used by the tunnel. Do not configure OAuth or another ChatGPT-side authentication method.
Never paste 127.0.0.1
, localhost
, the RepoRelay bridge secret, or an OpenAI runtime API key into ChatGPT. The tunnel connection does all the networking.
In the ChatGPT app flow, run Scan Tools and confirm RepoRelay exposes exactly these seven tools:
open_workspace
list_files
read_file
search_files
write_next_task
write_review
update_handoff_state
That is the expected normal surface. If Scan Tools shows shell, Git, process
execution, generic file editing, delete, patching, or any other unexpected
capability, stop and investigate before using the app — run
reporelay audit "C:\Projects\my-app" --json
and confirm the tool list.
Start a new chat, select the RepoRelay app, and try:
Open the approved repository and list its top-level files.
Then test the boundary:
Try to read .env.
The second request should be blocked.
You now have ChatGPT reviewing your repository through a verified security boundary. Useful prompts:
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.
The normal RepoRelay setup lets ChatGPT plan and review while a separate local
coding agent (Codex, Claude, or another) does the implementation. RepoRelay
coordinates them through a small .ai-handoff
workspace:
.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
Conceptually:
ChatGPT
↓ writes NEXT_TASK.md
Codex / local coding agent
↓ implements
↓ writes RESULT.md
ChatGPT
↓ reviews result
↓ writes REVIEW.md
STATE.json
coordinates the cycle. RepoRelay itself does not run Codex or Claude — they are separate local applications you start yourself. The handoff files are just a structured place to hand work back and forth.
ChatGPT can only write NEXT_TASK.md
, REVIEW.md
, and STATE.json
. The
implementer-owned RESULT.md
is never writable by ChatGPT.
See docs/handoff-cycle.md for the detailed protocol and examples/ for reviewer and implementer prompts.
After the one-time setup, do not recreate the tunnel or the ChatGPT app. Each day:
Start RepoRelay:
reporelay quickstart "C:\Projects\my-app"
Start the tunnel (in a second window):
reporelay tunnel run
Open ChatGPT, start a new chat, and select the existing RepoRelay app.
Keep both windows open while you use the app. If the connection stops working,
run reporelay tunnel doctor
again.
RepoRelay exposes one repository at a time.
Press
Ctrl+C in the RepoRelay terminal. - Start RepoRelay for the new repository:
reporelay quickstart "C:\Projects\another-repo"
Keep
tunnel-client
running. It reconnects to the restarted RepoRelay automatically (same port and protected bridge-secret file). If you used a different port, the managed tunnel follows it automatically. - Start a new ChatGPT conversation and select the RepoRelay app.
Ask ChatGPT to open the new repository.
Do not rescan tools just because the approved repository changed. Rescan only if the tool definitions changed or ChatGPT asks you to.
| You see | What to do |
|---|---|
'node' is not recognized |
|
| Node.js is not installed, or PowerShell was opened before the install finished. Install Node.js from | |
node --version . |
RepoRelay requires Node.js >=22.19 and <27
node --version
.'reporelay' is not recognized
npm install -g reporelay-mcp@latest
, close and reopen PowerShell, and try reporelay --version
.Cannot find module ... dist\cli.js
cd
into the RepoRelay
folder and run npm run build
first.C:Users\you\...
(path looks mangled)reporelay quickstart "C:\Users\you\Projects\my-app"
.Port 7676 is already in use
--port 7677
) — the managed tunnel follows the new port automatically. There is no quickstart --stop
; stop RepoRelay with Ctrl+C. On Windows, find the listener with Get-NetTCPConnection -LocalPort 7676 -State Listen AGENTS.md`
AGENTS.md
without the RepoRelay marker. RepoRelay will not overwrite it. Review the file first; if you want RepoRelay to preserve it and append the marked handoff instructions, rerun reporelay quickstart "..." --append-agent-instructions
.tunnel-client
missingreporelay tunnel setup
; it re-downloads and verifies the managed client.tunnel_
followed by 32 hex characters. Copy it again from Platform tunnel settings.Tunnels Read + Use. Rerunreporelay tunnel setup
.reporelay tunnel doctor
.reporelay tunnel doctor
.reporelay tunnel setup
.reporelay tunnel doctor
reports Ready.
, then rescan in a new app/chat.reporelay audit "C:\Projects\my-app" --json
and confirm the expected 7-tool list.reporelay quickstart "C:\Projects\my-app"
, then try again in a new chat.tunnel-client
stopped. Restart it with reporelay tunnel run
, then try again in a new chat.reporelay tunnel doctor
reports as the local MCP endpoint. Quickstart records the live endpoint automatically, or set it explicitly with reporelay tunnel setup --port <port>
.For anything else, run reporelay doctor
. It prints configuration and security status without printing secret values.
The normal RepoRelay experience is the 7-tool handoff surface above, and it is the recommended beginner setup. If you specifically want ChatGPT to inspect only — no handoff files, no writes at all — start with:
reporelay quickstart "C:\Projects\my-app" --no-handoff-writes
In this optional mode RepoRelay exposes exactly four tools:
open_workspace
list_files
read_file
search_files
Read-only mode does not create .ai-handoff
, does not create or modify
AGENTS.md
, and leaves the approved repository unchanged. All containment, authentication, and security checks still apply. Use the matching audit flag:
reporelay audit "C:\Projects\my-app" --no-handoff-writes
When you use this mode, expect 4 tools in Scan Tools instead of 7.
RepoRelay's enforced boundary includes:
- loopback-only binding and authentication required;
- exactly one existing canonical approved root;
- sensitive paths blocked, including
.env
, VCS metadata, credential stores, and private-key formats; - traversal, absolute outside-root paths, symlink/junction/reparse escapes, and hard-link bypasses blocked;
- bounded reads, searches, results, and handoff content;
- no shell, PowerShell, Git, process, generic write, patch, delete, artifact, worktree, skill, subagent, or local-agent tool;
- handoff writes limited to the three fixed pre-existing targets.
RepoRelay is a least-privilege application boundary, not an operating-system sandbox against malicious software already running as the same local user. An external Secure MCP Tunnel is a separate security boundary and must be secured independently. Choose the approved repository carefully.
See SECURITY.md for the full security model and
reporelay audit
documentation.
Most users never need these. When you do:
Configuration—REPORELAY_*
environment variables, bridge authentication, ports, logging, and handoff mode.ChatGPT Web setup details— the full tunnel and app reference.Windows operations— lifecycle scripts, scheduled tasks, and managed Windows setup.— placeholder configuration only. Never put a real bridge secret or tunnel credential in it..env.example
Local MCP clients— if your MCP client runs on the same computer as RepoRelay, you do not need the tunnel: point it at the local MCP URL printed by quickstart and send theX-RepoRelay-Bridge-Secret
header loaded from the protected file.
For configuration and security status without printing secret values:
reporelay doctor
- Node.js
>=22.19 <27
(npm is included); - Git for the clone-based install — optional if you download the ZIP instead.
The quickstart in this README works on Windows, macOS, and Linux. Windows 10/11 is the fully validated lifecycle and operational platform, including the PowerShell scripts and tunnel-managed runbook.
- One approved repository is exposed at a time.
- RepoRelay is not an operating-system sandbox.
- ChatGPT Web needs external OpenAI Secure MCP Tunnel infrastructure to reach a private local bridge.
- Windows is the fully validated lifecycle platform; other platforms do not have identical PowerShell/tunnel operations.
- Codex, Claude, and other coding agents are separate local applications, not components of RepoRelay.
ChatGPT Web setupSecurity modelConfigurationWindows operationsSetup notesHandoff cycleHandoff examplesContributing
RepoRelay is released under the MIT License. The project keeps its required upstream attribution and does not bundle the SDKs or runtimes of Codex, Claude, or other implementers.
npm ci
npm run typecheck
npm test
npm run verify:release
npm audit --audit-level=low
npm pack --dry-run --json
git diff --check