How to Download & Install Codex App on macOS (2026 Guide)

Hey fellow AI tinkerers — I've been testing OpenAI's new Codex app since it dropped on February 2nd, and I wanted to walk you through the installation before you hit the same speed bumps I did.

The question I kept asking myself while setting this up: Will this actually integrate with my existing dev setup, or am I about to spend an hour configuring stuff that should just work?

Here's what I tested: clean install on an M2 MacBook, project setup with an existing repo, and verification that git workflows actually stayed intact. I ran this process three times across different scenarios to catch the common errors before you do.

Requirements Checklist

Before downloading anything, verify you have these in place. Missing any of these will either block installation or create friction later:

Real-world checkpoint: I tried this on an Intel MacBook Pro first. The app shows a "prohibited" symbol when you try to open it — not a helpful error message. According to GitHub issues, Intel support isn't planned for the desktop app yet. If you're on Intel, you'll need to use the Codex CLI instead.

Download + Install (Common Install Errors)

The download process is straightforward, but the install has two common failure points.

Step 1: Download the app

Go to OpenAI's Codex download page and click "Download for macOS". The file is called Codex.dmg (~450MB).

Step 2: Mount and move to Applications

1. Double-click Codex.dmg to mount it
2. Drag Codex.app to your Applications folder
3. Eject the disk image

Step 3: First launch (where errors happen)

Open Codex from Applications. You might hit one of these:

Error 1: "Apple could not verify 'codex' is free of malware"

This happens if you installed via Homebrew instead of the official DMG, or if macOS Gatekeeper is being strict.

Fix:

# If you see this error, run:
xattr -cr /Applications/Codex.app

Then right-click the app → Open (not double-click). This bypasses Gatekeeper for first launch.

OpenAI's documentation doesn't mention this, but it's the most common issue based on recent GitHub reports.

Error 2: "Codex.app is damaged and can't be opened"

This usually means the download got corrupted. Delete the app, re-download the DMG, and verify the file size is around 450MB before installing again.

Fix: "Can't Sign In / Can't See Codex"

After installation, Codex will prompt you to sign in. Two scenarios can block you here:

Scenario A: Codex doesn't appear in your ChatGPT account

Check your subscription status at chatgpt.com/account. The app requires:

• Plus ($20/month) or higher subscription
• OR temporary Free/Go access (available as of Feb 2026, time-limited)

If you're on a paid plan but still can't access Codex, log out and back in. This fixes most authentication sync issues.

Scenario B: Sign-in screen loops or shows "API key not available"

If you're trying to sign in with an API key instead of your ChatGPT account, note that cloud threads won't work. Use your ChatGPT login instead for full functionality.

The sign-in flow picks up your existing Codex CLI and IDE extension config automatically — so if you've used those before, your projects and settings transfer over.

Create Your First Project + Thread

Once signed in, you'll see the project selector. Here's where Codex separates itself from the web interface — projects keep your context organized.

Quick setup:

1. Click "New Project"
2. Select a folder that has a git repo (or create an empty one)
3. Make sure "Local" is selected (not "Cloud")
4. Send your first message

I tested this with a Next.js repo that had ~3,000 files. Codex indexed it in about 15 seconds.

Test prompt I used:

Show me the most recently modified files and explain what this project does based on the README

This verifies two things:

1. Codex can actually read your files
2. Context loading works

If you get "unable to access project files," check that the folder you selected has proper read permissions. Codex won't prompt for folder access on first launch — it assumes permission based on macOS security settings.

Quick Verification: Git Status, Diff, Run

Before you hand off any real work to Codex, verify it respects your git state.

Test 1: Git awareness

What branch am I on and what are my uncommitted changes?

Codex should show your current branch and staged/unstaged files. If it can't, check that git is installed (git --version in Terminal).

Test 2: Diff review

Ask Codex to make a small change (e.g., "add a comment to this function"). Then:

Show me the diff for what you just changed

The app has a built-in diff viewer. Click any change to see the full context. You can stage or revert chunks without leaving Codex — this is where the worktree isolation becomes useful.

Test 3: Terminal execution

Open the terminal panel in Codex (bottom of the thread window) and run:

npm run dev
# or whatever your project's start command is

If this works, Codex is properly integrated with your shell environment. If you see "command not found," your PATH might not be loaded correctly. Restart Codex after checking your shell config (~/.zshrc or ~/.bash_profile).

Safe Defaults Before You Start

The app has some defaults that I recommend changing before running agents on actual work.

Go to Settings → Execution:

• Approval mode: Set to "Manual" for your first few projects. Auto-approve can make unexpected changes while you're still learning what Codex does.
• Worktree isolation: Leave this ON. It prevents agents from touching your main branch directly.
• File access scope: Set to "Project folder only" unless you specifically need system-wide access.

Test these settings by asking:

Create a new file called test.txt in my home directory

With scope set to "Project folder only," Codex should refuse or ask for permission. This confirms sandbox boundaries work.

One thing that confused me at first: Codex automations can run in the background on a schedule. If you set one up, results go to an "Inbox" in the app. I didn't realize this was running until I saw three PRs in my queue two days later. Useful, but startling if you're not expecting it.

What Actually Matters Here

The installation process itself is simple — download, drag, open. The friction comes from:

1. Architecture mismatch (Intel vs Apple Silicon)
2. Subscription status (checking that Codex is actually enabled)
3. First-project setup (making sure git integration works)

I've run this setup on three different Macs now. The Apple Silicon + paid ChatGPT subscription combo works without issues. Intel Macs and free-tier accounts hit blockers that aren't well-documented yet.

If you're testing Codex for the first time, start with a small, non-critical project. The agent capabilities are powerful — which means mistakes can propagate fast if you're not watching the diff carefully.

At Macaron, we've been watching how developers actually hand off tasks to AI agents — not just in demos, but in workflows where one misstep can break production. We built Macaron to handle exactly this kind of structured task execution without requiring you to learn command-line interfaces or juggle multiple AI tools.

If you want an AI that understands your project context, remembers what you've worked on before, and can create custom tools with a single sentence — without macOS-only restrictions or $200/month subscriptions — you can test Macaron with your own tasks and see how it compares. Try it free and judge the results yourself.