CodexPro on macOS — Setup Guide

This guide sets up CodexPro on macOS without assuming a particular Mac model, username, repository path, DNS hostname, tunnel provider, shell customization, or JavaScript package manager.

The normal flow is:

install CodexPro
      ↓
open the target repository
      ↓
codexpro setup
      ↓
codexpro start
      ↓
copy the generated MCP Server URL
      ↓
connect ChatGPT
      ↓
doctor / connection-test / repository verification

Requirements

Verify these prerequisites before setup:

1. a supported macOS installation;
2. Node.js 20 or newer;
3. one compatible package manager for installing the codexpro npm package;
4. Git;
5. Codex CLI if your workflow uses Codex-backed Bash/sandbox behavior;
6. a ChatGPT account that can create a custom MCP integration;
7. an HTTPS route when ChatGPT web must reach the Mac remotely.

Check the local tools:

node --version
git --version
codex --version 2>/dev/null || true

Node.js may be installed with a version manager, Homebrew, MacPorts, an enterprise software distribution system, or another controlled mechanism. CodexPro does not require one specific Node installer.

Install CodexPro

The upstream reference command uses npm:

npm install -g codexpro

A compatible package manager may be used instead as long as it installs the required package version and makes the codexpro executable available on PATH.

Examples:

# npm
npm install -g codexpro

# pnpm
pnpm add -g codexpro

# Bun
bun add -g codexpro

# Yarn Classic
# yarn global add codexpro

Verify the result independently of package-manager storage layout:

codexpro --version
command -v codexpro

Do not publish or hardcode a global package directory from another developer's Mac.

Initialize a repository

Move into the repository ChatGPT should be allowed to work with:

cd /path/to/your/repository

Run:

codexpro setup

Keep the allowed workspace as narrow as practical. Prefer a project root over your entire home directory.

Start CodexPro

For normal daily use:

codexpro start

To set the repository explicitly:

codexpro start --root /path/to/your/repository

Useful modes include:

codexpro start --no-bash
codexpro start --tool-mode minimal
codexpro start --tool-mode full
codexpro start --mode handoff
codexpro start --mode pro
codexpro start --headless

Choose the least-privileged mode that satisfies the task.

Local-only operation

For local-only operation:

codexpro start --tunnel none

This is useful for local validation or when you manage the HTTPS/reverse-proxy layer separately.

Do not directly publish the raw local MCP listener without the transport and authentication controls expected by CodexPro.

Public HTTPS options

ChatGPT web needs an HTTPS route to the running MCP endpoint.

Quick Cloudflare tunnel

For a temporary public URL:

codexpro start --tunnel cloudflare

Use this for evaluation or short-lived testing where a changing public URL is acceptable.

Stable Cloudflare hostname

Create persistent token state:

mkdir -p ~/.codexpro
openssl rand -hex 32 > ~/.codexpro/http-token
chmod 600 ~/.codexpro/http-token

Then use deployment-specific values:

codexpro stable \
  --hostname codexpro.example.com \
  --tunnel-name codexpro

Replace both values with your own hostname and tunnel name.

ngrok

codexpro ngrok --hostname your.ngrok-free.dev

Tailscale

codexpro tailscale --hostname your-device.your-tailnet.ts.net

Use only hostnames and accounts owned by the deployment being configured.

Connect ChatGPT

After startup, copy the exact Server URL emitted by CodexPro.

Create the custom MCP integration in ChatGPT with deployment-specific values:

Field	Value
Name	any clear deployment-specific name
Server URL	exact URL generated by CodexPro
Authentication	the mode required by the generated endpoint
Permissions	only the actions required by the workflow

If the Server URL carries a CodexPro token, the entire URL is a secret.

Never include it in public screenshots, Git history, issue descriptions, documentation examples, or shared terminal transcripts.

Verify the installation

Run:

codexpro doctor

If the ChatGPT connection does not work:

codexpro connection-test

Inspect the current setup when necessary:

codexpro settings
codexpro inspect
codexpro review

A minimum acceptance test should prove that:

• the intended repository opens successfully;
• file reads/searches stay within allowed roots;
• write tools appear only under the configured write policy;
• Bash behavior matches the selected mode;
• sensitive paths remain blocked;
• the chosen HTTPS route reaches this specific CodexPro process;
• ChatGPT can complete a read → controlled edit → verification loop on a disposable repository.

Multiple repositories

Allow multiple explicit repositories when that is part of the intended trust boundary:

codexpro settings set \
  --project ~/code/web \
  --project ~/code/api

codexpro settings show
codexpro start

Inside ChatGPT, select only the repository needed for the task.

For separate accounts or security domains, prefer separate processes and Server URLs rather than one broad process with excessive access.

macOS filesystem guidance

Prefer roots such as:

~/Developer/my-project
~/Projects/my-project
/Users/<user>/code/my-project

instead of broad roots such as:

/
/Users
~

Do not grant Full Disk Access merely to avoid selecting the correct repository root. Broader OS permissions should be a deliberate security decision, not a troubleshooting shortcut.

macOS privacy controls may restrict access to locations such as Desktop, Documents, Downloads, removable volumes, or other protected areas depending on how the terminal/runtime is launched. If access is denied, first move or select the intended repository location and review macOS privacy permissions before widening CodexPro's authority.

Shell and PATH considerations

On modern macOS, interactive shells commonly use zsh, while GUI-launched or supervised processes may receive a different PATH than your terminal session.

Check the actual executable:

command -v codexpro
which codexpro
printf '%s\n' "$PATH"

If CodexPro works in Terminal but not from a service or alternate shell, configure the service/process environment explicitly. Do not source an entire interactive shell profile containing unrelated credentials just to obtain one binary path.

Apple Silicon and Intel Macs

CodexPro itself is a Node.js package, so the critical point is that the Node.js runtime and any external native tools used by the deployment match the Mac architecture being used.

Check the machine architecture:

uname -m

Typical results are:

arm64
x86_64

If an external tunnel binary or other native dependency fails to start, verify that binary's architecture rather than changing CodexPro repository permissions.

Running headless

CodexPro exposes:

codexpro start --headless

Use headless mode only after interactive setup and validation are complete.

If you later manage CodexPro with launchd or another supervisor:

• use an explicit working directory;
• provide a minimal environment and explicit PATH;
• keep tokens outside the plist/repository where possible;
• run as the intended user rather than as root;
• avoid writing secrets to stdout/stderr;
• validate tunnel and repository access before enabling automatic restart.

The exact launchd plist is deployment-specific and should not embed a personal username, project path, token, or hostname in reusable documentation.

Update CodexPro

The upstream npm update form is:

npm install -g codexpro@latest
codexpro --version

With pnpm, Bun, Yarn, or another compatible package manager, use the equivalent update/install operation.

After an update:

1. record the new version;
2. restart CodexPro;
3. run codexpro doctor;
4. run codexpro connection-test when the remote route is involved;
5. verify workspace, write, and Bash boundaries again;
6. re-review any version-specific source patch before applying it to the new build.

Troubleshooting

codexpro: command not found

command -v codexpro
printf '%s\n' "$PATH"

Check the package manager's global executable directory. Do not copy a path from another Mac.

Works in one terminal but not another

Compare:

which node
which codexpro
printf '%s\n' "$PATH"

Version managers and GUI-launched shells can initialize differently. Make the runtime selection explicit.

ChatGPT cannot connect

Run:

codexpro connection-test

Then verify:

• CodexPro is still running;
• the public tunnel is healthy;
• the hostname points to the intended route;
• the Server URL in ChatGPT is current;
• token state has not changed;
• a local firewall, VPN, or network policy is not interfering with the tunnel.

Repository access is too broad

Restart with a narrower root:

codexpro start --root /path/to/specific/repository

macOS denies access to a folder

Do not immediately enable broad Full Disk Access. Confirm that the repository is in the intended location and review the privacy permission associated with the terminal/runtime launching CodexPro.

Bash is not required

Disable it:

codexpro start --no-bash

Acceptance checklist

• Node.js 20+ is installed.
• codexpro resolves on PATH without depending on another user's package-manager layout.
• The selected repository is an explicit allowed workspace.
• codexpro setup completes.
• codexpro doctor passes or has only understood environment-specific warnings.
• Local-only or public HTTPS mode matches the intended deployment.
• Public access uses the intended authentication/token model.
• Tokens and token-bearing URLs are not committed or published.
• macOS filesystem/privacy permissions are no broader than required.
• ChatGPT connects to the correct running process.
• Repository reads/writes remain inside allowed roots.
• Bash/write tools match the selected policy.
• A disposable end-to-end read → edit → verification workflow succeeds.

Recommended operational rule

Treat CodexPro as a repository-scoped development bridge, not as a general remote-control mechanism for the Mac. Keep the workspace narrow, OS permissions minimal, credentials private, and public routing tied to the exact process and repository intended for ChatGPT access.