2026 OpenAI Codex CLI Mac Deployment: A Safe Runbook

Symptom: You gave Codex CLI broad access to fix one test error, and now you cannot tell what it can read, write, or execute.

Fastest fix: Stop the session, return to a small repository with restricted credentials, and validate read-only, workspace-write, approval, and rollback behavior before touching production code.

This runbook is for independent developers, research teams, and environment administrators deploying OpenAI Codex CLI on Mac in 2026. It focuses on permissions, secrets, network access, long tasks, and recovery. It is not a model comparison or a feature tour.

Last updated: August 2, 2026. Installation, authentication, macOS support, and sandbox behavior were checked against OpenAI’s official Codex documentation, official repository, security notes, and current release records.

Start with the environment, not the command

The wrong first question is, “How do I install Codex CLI?”

The right question is, “What is this agent allowed to touch if I stop watching?”

A main Mac is acceptable when all three conditions are true:

• The task is short and interactive.
• The repository is low risk and easy to restore.
• You can keep unrelated files and credentials outside the workspace.

Choose an independent user account, spare Mac, or cloud Mac when any of these conditions apply:

• The repository contains private customer code or deployment logic.
• The task may run while you are away from the terminal.
• The Mac is shared with personal documents, credentials, certificates, or other repositories.
• You need a repeatable environment that can be reset after a failed trial.
• A long task must continue while your main Mac sleeps, reboots, or is used for other work.

The hidden cost of using a main Mac is not only a bad patch. It is unclear scope. An agent may need to inspect build tools, package managers, Git metadata, shell configuration, or local services. The broader the environment, the harder it becomes to prove what happened.

Default decision: low-risk short task on the main Mac; sensitive, unattended, or long task on an isolated environment.

Choose a starting environment

For a broader local-versus-remote decision, keep the deployment question separate from the model question. The environment determines whether a mistake is contained.

Install once, then verify the identity path

Use an installation method published by OpenAI. The current official repository lists the standalone installer, npm, Homebrew, and platform-specific releases. It also lists macOS 12 or later as supported, with 4 GB RAM as the minimum and 8 GB recommended in its installation notes. Check the official installation guide before copying a command.

One possible official route is:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

The repository also documents:

npm install -g @openai/codex

or:

brew install --cask codex

Do not mix installation methods during the first trial. Multiple binaries can create a misleading result where you update one copy but execute another.

After installation, record the result:

which codex
codex --version
sw_vers
uname -m

Save the output with the deployment record. The exact version matters when you later compare a permission failure, a changed configuration behavior, or a recovery result. If you need a repeatable environment, use the official release records to document the binary source and version used by each Mac.

ChatGPT sign-in versus API credentials

Codex CLI supports a ChatGPT sign-in path and an API-key path. They are not operationally identical.

With ChatGPT sign-in, you authenticate through the CLI flow. OpenAI’s help documentation describes using codex --login and selecting the ChatGPT sign-in option. With API authentication, you manage a credential directly and must define how it is stored, scoped, rotated, and revoked. See OpenAI’s Codex CLI authentication documentation.

The first launch is a verification step, not the beginning of production work.

Check:

/status

Then confirm the active account, workspace, model provider, and configuration path shown by the client. If the output is ambiguous, stop. Do not attach a production repository to an unknown identity.

Use the first hour to establish the permission baseline

The official Codex source describes three meaningful sandbox boundaries:

• read-only
• workspace-write
• danger-full-access

The macOS implementation uses Seatbelt to enforce filesystem and network policy. In workspace-write, writes are limited to configured writable roots, while network access remains a separate control. The project’s security documentation also explains that the resolved policy and writable roots determine the effective boundary. Read the official sandbox documentation and Codex security guidance.

The official configuration reference is useful when you need to turn the tested baseline into a repeatable file or team template. Record only the settings you have verified. Do not copy an old configuration into a newer release without checking whether the keys and defaults still match.

Use a test repository with:

• No API keys.
• No .env files.
• No certificates.
• No personal shell configuration.
• No production remotes.
• One intentionally editable file.
• One file outside the permitted workspace that must remain untouched.

Run four checks:

1. Ask Codex to list the repository files.
2. Ask it to propose a change without applying it.
3. Ask it to edit only the test file.
4. Ask it to run a harmless command that does not require network access.

Record the command, approval prompt, result, and changed files.

Do not treat high-permission mode as a troubleshooting shortcut. If a normal operation fails, identify whether the cause is a wrong working directory, missing dependency, denied network access, unavailable keychain item, or unsupported command. Moving to unrestricted mode only hides the boundary that failed.

A useful configuration baseline keeps the sandbox and approval policy explicit. The official project documentation identifies --sandbox read-only, --sandbox workspace-write, and --sandbox danger-full-access as distinct launch choices.

Make the first real task small and reversible

Your first real task should have a narrow objective. Examples:

• Add a test for one existing function.
• Rename a local symbol across one package.
• Fix a reproducible type error.
• Generate a reviewable documentation patch.

Avoid these first:

• Database migrations.
• Production deployment scripts.
• Authentication middleware.
• Broad dependency upgrades.
• Repository-wide formatting.
• Tasks that require access to personal credentials.

Before launch, create a clean checkpoint:

git status --short
git switch -c codex-trial
git diff --exit-code

Then define the allowed surface:

• One repository.
• One branch.
• One task.
• One task-specific credential.
• One approval rule.
• One rollback command.

The agent should not receive your entire home directory as a working area. A local repository can contain more than source code: Git hooks, build scripts, package manifests, ignored files, generated artifacts, and references to external services. Keep unrelated repositories outside the session.

Separate repository, secrets, and network

Treat each access request as a separate decision.

Repository access: launch from the intended checkout. Confirm the current path before asking for edits.

Secrets: use a credential created for the trial. Do not place it in the repository. Do not paste it into the conversation. Do not assume that a file is safe because it is listed in .gitignore.

Network: keep network access disabled or approval-gated until the task needs it. Package installation, external API calls, Git pushes, browser tools, and remote shell commands should have separate reasons.

The important distinction is between “the command succeeded” and “the command succeeded inside the intended boundary.” Only the second is a deployment result.

Test long tasks before you depend on them

A long Codex CLI task is not simply a short task with a larger prompt. It introduces continuity risk.

Test the recovery chain deliberately:

1. Start a bounded task in a disposable repository.
2. Capture the session identifier and working tree state.
3. Interrupt the terminal.
4. Simulate a network interruption.
5. Let the Mac sleep or close the lid if that matches normal use.
6. Reconnect and inspect the repository.
7. Resume only after checking the diff and process state.
8. Confirm whether the task resumed, stopped, or partially completed.

Do not claim that a task is recoverable because the terminal returned to a prompt. Recovery requires evidence from the session, working tree, logs, and final output.

For interactive work, you can watch each approval and stop quickly. For unattended work, you need:

• A stable online host.
• An independent workspace.
• A defined maximum task scope.
• A clear stop condition.
• A way to inspect output without trusting the final message.
• A rollback path that does not depend on the agent.

A main Mac is a poor long-task host if you regularly sleep it, reboot it, move between networks, or need the machine for unrelated work. A spare Mac provides physical separation. A cloud Mac provides a more resettable delivery model when you need a temporary environment without changing your daily workstation. It still requires credential, access, and network controls.

Use this first-week acceptance checklist

Do not declare the deployment ready because installation succeeded. Pass the environment only when you can produce evidence for all five categories.

• [ ] Record the official installation source and the exact output of which codex.
• [ ] Record the installed version with codex --version.
• [ ] Confirm the macOS version and CPU architecture.
• [ ] Confirm the active identity path: ChatGPT sign-in or API credential.
• [ ] Locate and protect the Codex configuration and credential storage.
• [ ] Run a read-only test in a repository with no secrets.
• [ ] Run a workspace-write test against one disposable file.
• [ ] Confirm an unrelated file cannot be modified.
• [ ] Confirm network access is blocked or approval-gated as intended.
• [ ] Run a test that requires package installation only after recording the reason.
• [ ] Use a task-specific credential with a documented revoke step.
• [ ] Complete one real task on a new branch.
• [ ] Review the full Git diff before accepting the result.
• [ ] Revert the task and confirm the repository returns to its checkpoint.
• [ ] Interrupt a task and test the actual resume or restart procedure.
• [ ] Record what happens after sleep, terminal closure, and network loss.
• [ ] Decide whether the main Mac remains suitable for this task class.
• [ ] Save the installation source, configuration baseline, approval rules, and rollback steps.

The acceptance decision should be explicit:

• Pass: low-risk tasks remain in the current setup.
• Conditional pass: interactive work is allowed, but unattended work moves elsewhere.
• Fail: any permission boundary, secret control, rollback step, or recovery test is unclear.

What should stay local, and what should move to a cloud Mac?

Use the main Mac when the task is short, visible, low risk, and easy to undo. That is the efficient option for code explanation, small test changes, and local review.

Use a separate account or spare Mac when the task needs stronger separation but still benefits from physical access, local tools, or attached devices.

Use a cloud Mac when the task needs temporary capacity, a clean image, remote availability, or a resettable environment. It is especially useful when your main Mac is also your personal workstation and cannot remain online for a long task.

Do not rent an isolated environment for every small edit. The extra setup is not free. It adds delivery time, remote access steps, and another place to maintain credentials. Isolation pays for itself when the cost of an accidental read, write, secret exposure, or interrupted task is higher than the setup effort.

If you need a managed remote environment, review the MacHTML console and the MacHTML help center before choosing a delivery workflow. For a temporary trial, start with a non-production repository and document the environment handoff.

The deployment conclusion

The safe 2026 approach is not “install Codex CLI and grant it everything.” It is a staged deployment:

1. Select the smallest suitable Mac environment.
2. Install from an official OpenAI source.
3. Verify the binary, version, account, and configuration.
4. Start read-only.
5. Move to workspace-write only for a bounded repository.
6. Keep secrets task-specific and revocable.
7. Approve network and privileged operations individually.
8. Test interruption and rollback before long tasks.
9. Move sensitive or unattended work to an independent or cloud Mac.

Your current setup may be fine for short, low-risk development. Its weaknesses appear when it mixes personal files, broad credentials, unstable connectivity, and long-running automation. A main Mac is also difficult to reset cleanly after a failed experiment.

If you do not have a spare device, or you need a continuously available environment for an isolated trial, renting a Mac through MacHTML can be the more controlled option. You avoid changing your daily machine, can separate the test workspace from personal data, and can end the environment instead of carrying its permissions forward. Start by saving the MacHTML deployment guidance and complete the acceptance checklist before connecting any production repository.

FAQ