Quick Start

Quick Start

For a normal installation, install the release first and then run the guided wizard. Manual foreground startup remains available when you do not want the background service.

Linux and macOS:

curl -qfsSL https://codexify.dev/install.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://codexify.dev/install.ps1 | iex"

Restart the terminal after installation so ~/.codexify/bin is on PATH.

---

The guided wizard (recommended)

codexify 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 ~/.codexify/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 ~/.codexify/codexify.config.json (honoring CODEXIFY_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. Starting or restarting Codexify. If the release installer registered the background service, quickstart updates its config and restarts it automatically. Otherwise the wizard can start Codexify in the current terminal; keep that foreground process running while using the connector.

Useful flags:

codexify quickstart --config /path/to/codexify.config.json   # write elsewhere (default: ~/.codexify/codexify.config.json)
codexify 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 project root and tunnel to ~/.codexify/codexify.config.json (or another explicitly selected config):

   {
     "workDir": "/absolute/path/to/your/project",
     "openaiTunnel": {
       "tunnelId": "tunnel_0123456789abcdef0123456789abcdef",
       "apiKeyRef": "env:CONTROL_PLANE_API_KEY"
     }
   }

4. Export the runtime key and start in the foreground, or install/restart the background service:

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

On first use, Codexify 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 ~/.codexify/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:

codexify --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:

codexify --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 codexify.config.json option.
• How It Works — what happens on each tool call.