Getting started
Connect your first project, step by step
Prepare your account, choose a folder and finish connecting in ChatGPT. The app guides you through every step.
Before you start
- Your ChatGPT account with permission to add custom apps and access to Secure MCP Tunnels in OpenAI.
- Docker 24 or later running. Check Docker Desktop’s licence terms for your usage.
- Permission in your OpenAI organization to create a restricted credential and a tunnel.
- A local project directory you are willing to connect.
Roles and permissions
Creating a tunnel and a restricted credential needs the corresponding role in your OpenAI organization. Ask an owner if the option is not available to you. TunnelGPT never creates these for you.
Create or reuse a credential
Use a restricted credential scoped to what the tunnel needs. One reusable credential can serve several authorised tunnels without mixing project identities. Store nothing in a file; the desktop app keeps it in operating-system secure storage.
Create and select the tunnel
Create a Secure MCP Tunnel and associate it with the ChatGPT workspace where you will use the connector. Copy its full identifier to paste into TunnelGPT.
Register the project
Select the folder in TunnelGPT and give it a recognizable name. Link it to that project’s tunnel. Start in read-only mode.
Start and verify the connection
Start the connection and wait for TunnelGPT to report that it is ready. Keep the computer awake, online and running Docker.
Configure it in ChatGPT
Open Plugins on chatgpt.com and create a custom app. Under Connection choose Tunnel, then select your project’s tunnel or paste its identifier. Follow the authentication fields in the app’s guide, scan the tools and save the connector.
Common problems
- Connector added before the readiness check passed — start the profile first, then add it.
- Tunnel ID pasted with surrounding whitespace or truncated — it must match exactly.
- Docker is not running — start it before the connection.
- Two profiles pointing at one tunnel — one connected tunnel per active profile.
- Credential lacking the scope the tunnel needs — check the role, then reissue.
Official documentation
Tunnel and connector behaviour is defined by OpenAI, not by us. Follow their documentation for anything about the tunnel itself.
Resume the same task in another conversation.
Select your project’s connector in ChatGPT and describe a clear task. TunnelGPT automatically records file changes and project jobs in private app storage; you do not need a checkpoint file in your project. Ask ChatGPT to update the goal or next step when needed. In another conversation, select the same connector and describe the goal or file you want to continue working on. Ask ChatGPT to find the matching saved task and resume it. If several tasks match, clarify the goal or filename. The agent manages the task identifiers. The app checks available receipts and job states; unresolved actions stay pending. Separate tasks keep separate context. Memory is bounded and old resolved history is cleaned automatically. It does not save the whole chat or give different chats separate access permissions. Refresh the connector’s tools after updating the app.
Connect a local MCP
In TunnelGPT, open Local MCPs → Add a local MCP. Enter its local HTTP address or the full path to its installed executable. Reuse your saved Restricted key and enter a separate tunnel ID. Save and check tools, select the tools you want, confirm their permissions, then choose Connect to ChatGPT. Finally, add that tunnel as a custom connector in your ChatGPT account.
The local HTTP server must already be running. For an installed command, TunnelGPT starts it when you test or connect. Optional arguments and environment variables are under Advanced configuration; secrets are stored in the system keychain. Saving and testing alone do not expose tools remotely.
Let your local agent set it up.
To let your agent configure it: in Local MCPs, open Agent-assisted setup and choose Enable local agents. Copy the command for Codex or your MCP client’s JSON configuration. Keep TunnelGPT open and ask the agent to add and check your local MCP. Provide the tunnel ID and the tools you authorize; it can reuse a saved key. You can disable this access in the app and review its recent operations.
For macOS on Apple Silicon (M1 or later). Local MCPs keep their own permissions, including access to signed-in accounts or changes outside a project folder. Connect trusted servers and review their tools. ChatGPT connector access depends on your account.