FAQ

FAQ

Short answers to common questions. Each links to the page with the full story.

---

What is Codex Free, in one sentence? A local MCP bridge server that lets ChatGPT Web Pro call tools on your machine — read/write files, run commands, git, search, patch, drive processes — pinned to a directory you choose, over an outbound-only tunnel with no public URL. See Home.

Do I need to know Rust? No. You run a prebuilt binary and edit a JSON config. Rust only matters if you build from source. See Installation.

Does it open a port on my machine? Not in native tunnel mode — it binds 127.0.0.1 and the tunnel client dials out to OpenAI. Only the legacy/external mode binds 0.0.0.0:3000, and that must sit behind your own authenticated proxy. See How It Works and Security Model.

Is it safe to point at any folder? Treat everything in the work directory (and, in multi-project mode, the whole access-root subtree) as read/write reachable by whoever can use the connector. The command allowlist is a guardrail against accidents, not a sandbox. Don't point it at directories you don't trust the model with. See Security Model.

How many tools does ChatGPT get? 27 in single-project mode, 29 in multi-project mode; one fewer if artifactIngress.enabled is false; plus any tools from bridged MCP servers. See Tools Reference.

Why does my chat "forget" the plan between sessions? It shouldn't — task state persists in ~/.codex-free/projects/…/memory.json and returns via instructions or one recall. If it truly forgets, memory.enabled may be false, or you're in a brand-new multi-project chat that hasn't selected its project yet. See Context and Memory.

Why is the model rewriting files instead of patching them? It didn't read the agent brief. Open the chat with "Call get_agent_brief and follow it for the rest of this chat." The brief carries Codex's editing constraints (apply_patch over rewrites, dirty-worktree rules, etc.). See Connecting to ChatGPT.

Can one server handle several repositories? Yes — --multi-project turns --work-dir into an access root and each chat selects its own project. See Multi-Project Mode.

Can two chats work on the same repo at once? Yes, safely — managed worktrees give the second chat its own checkout. See Worktree Isolation.

How do I show ChatGPT only what changed? show_changes with since: "last_review" (incremental) or "project_open" (full task diff). Compatible connectors render a review card. See Review Checkpoints.

Can I use my other MCP servers through this? Yes — Codex Free aggregates local stdio and remote Streamable HTTP servers and re-exposes their tools, and can auto-import from Codex's config. See Bridging MCP Servers.

Where do I put the OpenAI runtime key? Never as a literal in config — use env:NAME or file:/path via openaiTunnel.apiKeyRef. Use a restricted key (Tunnels Read + Use), not an admin key. The wizard stores it in a locked-down file: reference. See Connecting to ChatGPT and Security Model.

Can I record what ChatGPT did? Yes — --audit <file> writes a privacy-preserving JSONL log (hashes, timings, sizes, redacted argument shapes; no payloads). See Audit Logging.

Does it modify Codex's own config? No. It reads $CODEX_HOME/config.toml (for MCP servers and project candidates) but never rewrites it. See Bridging MCP Servers and Multi-Project Mode.

Which OSes are supported? Windows, macOS, and Linux natively — no WSL or POSIX-emulation layer. Prebuilt binaries cover x64 and arm64. See Installation.

Why does exec_command behave non-interactively? It runs with plain pipes, not a PTY (tty: true is rejected). Programs that only enable interactive behaviour on a real terminal will act as if piped. See Tools Reference.

Is this affiliated with OpenAI? No. Codex Free is an independent open-source project (MIT) that ports Codex's tool schemas and behavioural brief and uses OpenAI's official tunnel client. It still requires your own ChatGPT subscription.

---

Didn't find it? Check Troubleshooting or open an issue.