Quick Start

Quick Start

Two ways to get running: the guided wizard (best for a first install) or a manual start.

---

The guided wizard (recommended)

codex-free quickstart

From a source checkout:

cargo run --release -- quickstart

The wizard walks you through everything:

1. Which directory ChatGPT may access, and whether it's a single project or a multi-project access root (see Multi-Project Mode).
2. Creating an OpenAI Secure MCP Tunnel — it prints the exact OpenAI Platform link.
3. Entering the tunnel ID and a restricted runtime API key. The key is typed without terminal echo and stored in a dedicated per-tunnel file under ~/.codex-free/openai-tunnel/credentials/. On Unix, that directory and file are locked to your user. Your config receives only a file: reference — never the key itself — and any unrelated settings already in that file are preserved. By default the wizard writes the user-level config at ~/.codex-free/codex.config.json (honoring CODEX_FREE_CONFIG if set); pass --config to write elsewhere.
4. Creating the matching ChatGPT developer-mode connector — it prints the ChatGPT link and the exact values to enter.
5. Optionally starting the server immediately so ChatGPT can scan the live connector. Keep that process running while you use the connector.

Useful flags:

codex-free quickstart --config /path/to/codex.config.json   # write elsewhere (default: ~/.codex-free/codex.config.json)
codex-free quickstart --work-dir /path/to/project           # change the directory shown first

That's the whole setup. Jump to Connecting to ChatGPT to finish the ChatGPT side, then open a chat with:

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

Task: <what you want done>

---

Manual start (native tunnel)

If you'd rather not use the wizard:

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

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

3. Add the tunnel to codex.config.json in your project:

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

4. Export the runtime key and start:

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

On first use, Codex Free downloads the pinned runtime-only build of OpenAI's official tunnel client, verifies the archive against a SHA-256 embedded in this build, and installs it under ~/.codex-free/openai-tunnel/. It reports ready only after the runtime's /readyz check succeeds and a control-plane poll shows healthy. See Connecting to ChatGPT for the ChatGPT-side steps.

---

Manual start (local / external tunnel)

Without an openaiTunnel block, the server keeps its legacy behavior — it binds 0.0.0.0:3000, serves MCP at /mcp, and serves /health:

codex-free --work-dir /path/to/your/project

This is for local clients or an explicitly authenticated reverse proxy/tunnel you put in front of it. Do not publish this mode without authentication and network-level access controls — read Security Model first.

---

Serving many projects at once

Point the server at a common parent directory and enable multi-project mode:

codex-free --work-dir /path/to/projects --multi-project

Now --work-dir is an access root, and each ChatGPT conversation picks its own project beneath it with set_project_root / list_projects. Full details in Multi-Project Mode.

---

What to read next

• CLI Reference — every flag and command.
• Configuration — every codex.config.json option.
• How It Works — what happens on each tool call.