Connecting to ChatGPT

Connecting to ChatGPT

Codexify connects to ChatGPT through a developer-mode connector. There are two connection styles: the native OpenAI tunnel (recommended — no public URL) and an externally managed tunnel (you run the proxy).

---

With the native OpenAI tunnel (recommended)

1. In ChatGPT, enable Developer mode.

2. Configure openaiTunnel in codexify.config.json (or use codexify quickstart), export the referenced runtime key, and start Codexify. Keep the process running for connector discovery and every tool call.

3. In ChatGPT's connector/plugin settings, create a developer-mode connector with Connection type: Tunnel.

4. Select the same tunnel ID that Codexify reports as ready. Set Authentication to None.

5. Set the connector's permissions to Allow all actions if you don't want per-call confirmations.

6. Enable the connector in a new chat and open with:

   Call get_agent_brief and follow it for the rest of this chat.
   
   Task: <what you want done>
   

There is no server URL to enter in this mode. OpenAI routes the selected tunnel to the supervised client, which supplies Codexify's generated per-process bearer on the local hop. The startup banner prints the runtime-only /readyz and /metrics URLs; it does not advertise an admin UI because tunnel-client-runtime omits that surface.

Optional: gate the connector with a shared secret

Set conversationAuthToken in codexify.config.json (exactly 64 lowercase hex characters) to require each new chat to prove it before any tool works. When it's set, every tool except the gate is refused until the conversation presents the token once. On the ChatGPT wire the gate is deliberately named setup and its parameter ref (rather than authenticate/token) so ChatGPT's connector safety heuristic doesn't misread a token-shaped call as a secret leak and refuse it — ref still carries the exact token. Paste the one-line instruction into a chat or ChatGPT Project instructions:

To use this connector in a chat, call its `setup` tool once with ref `[REF]`.

After a successful call the grant is remembered for that ChatGPT conversation (restored across MCP reconnects and restarts from a hashed record under ~/.codexify/conversation-authorizations/, or scoped to the transport session for non-ChatGPT clients). Leave it unset to allow any conversation that can reach the connector. The wizard does not create this token — add it by hand. See Configuration and Security Model.

One-time tunnel setup

1. Create or obtain a tunnel ID in OpenAI Platform → Tunnels.

2. Create a restricted runtime API key whose principal has Tunnels Read + Use for that tunnel. Keep tunnel-management/admin credentials separate.

3. Reference the key from config — never paste the literal key:

   {
     "openaiTunnel": {
       "tunnelId": "tunnel_0123456789abcdef0123456789abcdef",
       "apiKeyRef": "env:CONTROL_PLANE_API_KEY"
     }
   }

4. Provide the key and start:

   export CONTROL_PLANE_API_KEY='...'
   codexify --work-dir /path/to/your/project

The wizard (codexify quickstart) does all of this for you and stores the key in a locked-down file: reference under ~/.codexify/openai-tunnel/credentials/ — see Quick Start.

Using a preinstalled tunnel client

Set openaiTunnel.clientPath or pass --openai-tunnel-client /path/to/tunnel-client-runtime. Codexify still checks the binary's version surface and required flags before starting it.

---

With an externally managed tunnel

1. Start Codexify without openaiTunnel (add --multi-project for one connector shared across projects).
2. Put an authenticated reverse proxy or tunnel in front of port 3000.
3. Create a URL-based developer connector whose server URL is the resulting HTTPS URL with /mcp appended.
4. Configure the connector authentication your client supports, and enforce access controls at the proxy/tunnel layer.

ngrok http 3000 is fine for a disposable connectivity test, but an unprotected public URL is not an appropriate long-lived deployment. Use provider access policies, source restrictions, mTLS, OAuth, or another control. --api-key helps MCP clients that send a static bearer, though ChatGPT's connector auth may not support that form directly. Read Security Model before exposing this mode.

---

Onboarding a chat

instructions is the proper channel, but ChatGPT Web isn't reliable about showing it to the model. One line fixes that:

Call get_agent_brief and follow it for the rest of this chat.

Task: <what you want done>

Everything — the shell you're on, the allowlist, your repo's AGENTS.md, any saved plan — arrives with that one call. If a chat drifts back into generic-assistant behaviour, ask for the brief again to re-anchor it.

Multi-project chats

Select the project first. With an exact path:

Call set_project_root with path "my-project", then call get_agent_brief and follow it for the rest of this chat.

Task: <what you want done>

By intent (let the agent search):

Call list_projects with a query derived from the task. If exactly one candidate is unambiguous, pass its selector to set_project_root; otherwise ask me which project I mean. Then call get_agent_brief and follow it for the rest of this chat.

Task: <what you want done>

On a later turn in an already-bound chat, the path doesn't need repeating — just get_agent_brief. A conversation cannot switch projects once bound; start a new chat for a different project. See Multi-Project Mode.

---

See also

• Quick Start — the guided path through all of this.
• Security Model — what "Allow all actions" actually grants.
• Troubleshooting — connector not appearing, tools missing, etc.