• Container Architecture
• Building the Container Image
  • Build Arguments
• Authentication Setup
  • Using OPENAI_API_KEY
  • Environment File Option
  • Optional Variables
  • Verifying Authentication
• Azure OpenAI Setup
  • Environment Variables
  • Configure ~/.codex/config.toml
  • Docker Run Examples (Azure)
• Working with Codex CLI from the Container
  • Basic Usage Pattern
  • Volume Mounts Explained
  • Working Directory Context
• Usage Examples
  • Interactive Session
  • Single Command Execution
  • Shell Alias for Convenience
• File Permissions
  • Option 1: Build with Custom UID
  • Option 2: Fix Permissions After Creation
• Troubleshooting
  • Authentication Issues
  • File Access Issues
  • Container Issues

A containerized environment for running the OpenAI Codex CLI. This image provides a rootless, minimal setup so you can run codex commands with local file access and API key–based authentication.

• Rootless execution: Runs as user codex (UID 1000) instead of root
• Minimal base: Uses node:22-slim for a smaller attack surface
• CLI entrypoint: Container entrypoint is codex

Build from the provided Dockerfile:

docker build -t codex-cli:dev .

Customize via build args if needed:

docker build \
  --build-arg CODEX_CLI_VERSION=latest \
  --build-arg USERNAME=codex \
  --build-arg UID=1000 \
  --build-arg GID=1000 \
  -t codex-cli:dev .

The Codex CLI authenticates with OpenAI using an API key. Pass your key as an environment variable when running the container.

Avoid placing secrets directly on the command line (they can leak via shell history and process inspection). Use an ephemeral prompt and pass the variable through:

# Prompts without echoing; does not store secret in history
read -s OPENAI_API_KEY && \
docker run -it \
  -v ${PWD}:/work \
  -e OPENAI_API_KEY \
  --rm codex-cli:dev --help; \
unset OPENAI_API_KEY

# Create a protected env file (avoid echoing secrets in your history)
install -m 600 /dev/null .env

# Edit securely with your editor to add keys
${EDITOR:-vi} .env

# Example contents to add (edit in the editor):
# OPENAI_API_KEY=...
# OPENAI_ORG_ID=org_...
# OPENAI_PROJECT=proj_...
# OPENAI_BASE_URL=https://api.openai.com/v1

# Use the environment file with Docker
docker run -it -v ${PWD}:/work --env-file .env --rm codex-cli:dev --help

Security tips for env files:

• Keep .env out of version control (add to .gitignore).
• Restrict permissions to owner read/write only (chmod 600 .env).
• Prefer short‑lived keys and rotate regularly.

• OPENAI_ORG_ID: Organization identifier if required by your account
• OPENAI_PROJECT: Project identifier for scoping usage
• OPENAI_BASE_URL: Alternate base URL if using a proxy or compatible endpoint

Run a simple command and confirm it executes without auth errors:

docker run -it -v ${PWD}:/work --env-file .env --rm codex-cli:dev --version

Use this if your OpenAI models are deployed on Azure OpenAI. You will need:

• An Azure OpenAI resource and at least one model deployment name (e.g., a chat model and optionally an embeddings model)
• The Azure OpenAI API key for that resource

There are two supported ways to configure Codex for Azure: via environment variables or via a config file at ~/.codex/config.toml (as described in Microsoft’s guide).

Set these to point Codex at your Azure OpenAI endpoint:

• AZURE_OPENAI_API_KEY: Your Azure OpenAI resource API key
• OPENAI_BASE_URL: Your Azure endpoint base URL, typically https://<resource-name>.openai.azure.com/openai
• OPENAI_API_VERSION: The Azure OpenAI API version, for example 2024-05-01-preview

When targeting a specific deployment, pass it as the model name (the deployment name), for example with --model <your-deployment-name> when invoking Codex commands.

Example .env for Azure:

AZURE_OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_BASE_URL=https://<your-resource>.openai.azure.com/openai
OPENAI_API_VERSION=2024-05-01-preview

Codex also supports a TOML config file in your home directory. This is useful to persist Azure settings and deployment names without repeating flags. Create ~/.codex/config.toml on your host with content like:

# ~/.codex/config.toml
[default]
provider = "azure-openai"

[providers.azure-openai]
# Your Azure OpenAI resource endpoint (no trailing /openai path needed here)
endpoint = "https://<your-resource>.openai.azure.com"
api_version = "2024-05-01-preview"

# Deployment names you created in the Azure OpenAI resource
chat_deployment = "<your-chat-deployment>"
embedding_deployment = "<your-embeddings-deployment>"

# Use this environment variable for the API key
api_key_env = "AZURE_OPENAI_API_KEY"

Notes:

• Mount your host home directory into the container so Codex can read ~/.codex/config.toml at /home/codex/.codex/config.toml.
• Keep your API key out of the file; the key is read from the environment variable specified by api_key_env.

Using environment variables only (without exposing secrets on the command line):

# Prompt for the Azure key without echoing
read -s AZURE_OPENAI_API_KEY && \
docker run -it --rm \
  -v ${PWD}:/work \
  -e AZURE_OPENAI_API_KEY \
  -e OPENAI_BASE_URL="https://<your-resource>.openai.azure.com/openai" \
  -e OPENAI_API_VERSION="2024-05-01-preview" \
  codex-cli:dev --help; \
unset AZURE_OPENAI_API_KEY

Using ~/.codex/config.toml plus an .env file that only carries the key:

# Ensure ~/.codex/config.toml exists on host; .env carries only the key
# Create protected .env (once):
install -m 600 /dev/null .env
${EDITOR:-vi} .env

# In .env, add only:
# AZURE_OPENAI_API_KEY=...

docker run -it --rm \
  -v $HOME:/home/codex \
  -v ${PWD}:/work \
  --env-file .env \
  codex-cli:dev --help

Use a working directory mount so Codex can read/write files in your project.

docker run -it -v ${PWD}:/work --env-file .env --rm codex-cli:dev [CODEX_ARGS]

Replace [CODEX_ARGS] with the arguments supported by your installed @openai/codex version (see --help).

• -v ${PWD}:/work: Maps your current directory into the container working directory
• --rm: Removes the container after the command finishes
• -it: Interactive TTY for prompts and multi-step workflows

The image sets /work as the working directory. This means:

• Files in your current directory are accessible within the container
• Output files are written back to your current directory
• Relative paths behave as expected

Start an interactive session to run multiple Codex commands:

docker run -it -v ${PWD}:/work --env-file .env --rm codex-cli:dev

Run a single command, for example to see help or version information:

# Help
docker run -it -v ${PWD}:/work --env-file .env --rm codex-cli:dev --help

# Version
docker run -it -v ${PWD}:/work --env-file .env --rm codex-cli:dev --version

Create a shell alias for shorter commands:

# Add to your ~/.bashrc or ~/.zshrc
alias codex='docker run -it -v ${PWD}:/work --env-file .env --rm codex-cli:dev'

# Then simply use:
codex --help

The container runs as user codex with UID 1000. If your host user has a different UID/GID, you may encounter permission issues. To resolve this:

docker build \
  --build-arg UID=$(id -u) \
  --build-arg GID=$(id -g) \
  -t codex-cli:dev .

# If files are created with unexpected ownership
sudo chown -R $(id -u):$(id -g) ./path-to-files

• Missing or invalid API key: Ensure OPENAI_API_KEY is set (via -e or --env-file)
• Org/project scoping: If required, set OPENAI_ORG_ID and/or OPENAI_PROJECT

• Files not visible: Confirm -v ${PWD}:/work is included
• Wrong ownership: Rebuild with your UID/GID or adjust ownership afterward

• Container fails to start: Verify Docker is running and the image built successfully
• Command not found: Ensure arguments come after the image name and use --help to list supported commands