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.
- On Mac, 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 and ask the agent to keep the task’s goal and next step current. Task memory stays in private app storage. In TunnelGPT, open Continue work on that project, select the task and check its jobs. Copy or save the summary, then paste it into another conversation with the same connector. If ChatGPT stops responding, use the task’s help action to check local work first: a job may still be running. Available receipts and job states are checked; unresolved actions stay pending. Optional Mac notifications report observable local changes, not the state of ChatGPT’s response. Separate tasks keep separate context but share the project permissions. When agents work in parallel, assign separate files or coordinate edits. Refresh the connector’s tools after updating. Find a task by its goal or filename; if several tasks match, clarify which one. Memory has storage limits and automatically cleans old resolved history.
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.