tool-containers
Search docs…Ctrl K
Menu
GitHub (opens in new tab)

Run Codex CLI with Docker

run.sh starts Codex CLI on the current directory, passing any arguments to codex. airgapped.run.sh does the same from a saved image on a host that cannot pull.

Images
  • GHCRghcr.io/hambn/codex
  • Docker Hubdocker.io/hambn/codex
Use case
Interactive coding on a local checkout
Upstream
github.com/openai/codex (opens in new tab)
Source
tools/ai/codex/docs/docker (opens in new tab)
On this page

Prerequisites

  • Docker Engine 23 or later.
  • An OpenAI API key in OPENAI_API_KEY.

Run Codex

Shell
export OPENAI_API_KEY=sk-...
./run.sh                                   # interactive session
./run.sh exec "summarize this repository"  # one-shot task

The interactive session opens Codex's sign-in screen with your key already detected; choose the API key option to continue. Codex saves the login in /home/sysadmin/.codex inside the container, and --rm deletes it when you exit, so you confirm it again on each run.

codex exec does not read OPENAI_API_KEY. It reads CODEX_API_KEY, which the scripts do not forward, so for non-interactive runs add -e CODEX_API_KEY to the docker run line and export the key under that name.

Run without registry access

On a machine that can pull, save the image:

Shell
docker save ghcr.io/hambn/codex:ubuntu-browser -o codex.tar

Copy codex.tar to the offline host and run it from there. The first argument is the tar path; the rest go to codex:

Shell
./airgapped.run.sh codex.tar

The script loads the tar and runs CODEX_IMAGE with --pull=never, so set CODEX_IMAGE if you saved a different tag.

Variables

Variable Required Purpose
OPENAI_API_KEY yes Forwarded to the container and offered at the Codex sign-in screen.
CODEX_IMAGE no Image both scripts run. Defaults to ghcr.io/hambn/codex:ubuntu-browser; set ghcr.io/hambn/codex@sha256:<digest> to pin one build.

Workspace

The current directory is mounted at /workspace, the image's working directory. Codex runs as sysadmin (UID 1000), so new files belong to UID 1000 on the host.

Files

  • run.sh pulls the image if needed and runs it.
  • airgapped.run.sh loads a saved tar and runs it without pulling.

File contents

airgapped.run.sh19 lines
#!/usr/bin/env bash
# Offline host: load the image from a tar saved on an online host, never pull.
#   docker save ghcr.io/hambn/codex:ubuntu-browser -o codex.tar
set -euo pipefail
: "${OPENAI_API_KEY:?Set OPENAI_API_KEY}"

image=${CODEX_IMAGE:-ghcr.io/hambn/codex:ubuntu-browser}
tar=${1:-codex.tar}
shift $(($# > 0 ? 1 : 0))
[[ -f "$tar" ]] || {
    echo "missing $tar; docker save it on an online host first" >&2
    exit 1
}

docker load -i "$tar"
docker run -it --rm --pull=never \
    -e OPENAI_API_KEY \
    -v "$PWD:/workspace" \
    "$image" "$@"
run.sh10 lines
#!/usr/bin/env bash
# Run Codex against the current directory.
set -euo pipefail
: "${OPENAI_API_KEY:?Set OPENAI_API_KEY}"

image=${CODEX_IMAGE:-ghcr.io/hambn/codex:ubuntu-browser}
docker run -it --rm \
    -e OPENAI_API_KEY \
    -v "$PWD:/workspace" \
    "$image" "$@"

Topics