# openai/codex-universal architecture

> Architecture diagram of the GitHub repository openai/codex-universal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openai/codex-universal
- Repository: https://github.com/openai/codex-universal

## Overview

##### Project type and purpose
- This is a Docker‐based reference implementation (“codex‐universal”) that builds and configures a base image for OpenAI Codex.
- Its primary goal is to provide a local image that mirrors the Codex environment (multiple language runtimes, tools, and entrypoint scripts) for development and debugging.

##### File structure
Top‐level files and directories:
- .github/workflows/build-image.yml – GitHub Actions pipeline that builds & publishes the image
- Dockerfile – instructions to install runtimes and tools
- entrypoint.sh – container entrypoint that invokes setup
- setup_universal.sh – script that reads CODEX_ENV_* variables and installs language versions
- LICENSES/ – licensing and SBOM outputs
- README.md – usage, supported versions, included packages
- setup scripts and CI config imply a CI/CD → Docker image → registry → user workflow

##### README for additional insights
- Describes how environment variables (CODEX_ENV_PYTHON_VERSION, etc.) drive runtime installation
- Lists supported versions and extra tools (pyenv, corepack, bazel, etc.)
- Shows usage: docker pull + docker run with env vars, volume mount, working directory

##### Final recommendations
- Be exhaustive: break the container internals into sub‐components (entrypoint vs. setup vs. individual installers).
- Step with key file names (e.g., build-image.yml, Dockerfile, entrypoint.sh).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"  
        direction TB
        DevCommit["Developer Commits"]:::external
        GHActions["GitHub Actions CI"]:::build
        DockerfileNode["Dockerfile"]:::build
        BuildImageYML["build-image.yml"]:::build
        Registry["Container Registry (ghcr.io)"]:::external
    end

    DevCommit -->|"triggers build"| GHActions
    GHActions -->|"uses"| BuildImageYML
    GHActions -->|"reads"| DockerfileNode
    GHActions -->|"push image"| Registry

    %% Runtime Flow
    subgraph "Developer Runtime"  
        direction TB
        DevMachine["Developer Machine"]:::external
        DockerEngine["Docker Engine"]:::build
        DockerImage["codex-universal Image"]:::build
        subgraph "Container Runtime"  
            direction TB
            Entrypoint["entrypoint.sh"]:::runtime
            SetupScript["setup_universal.sh"]:::runtime
            subgraph "Language Installers"  
                direction TB
                Pyenv["pyenv Installer"]:::runtime
                NvmRustGo["nvm/rustup/go/swift Installers"]:::runtime
            end
            subgraph "Pre-installed Tools"  
                direction TB
                RubyBunJava["ruby, bun, java, bazelisk"]:::runtime
            end
        end
        Workspace["Mounted User Workspace"]:::external
    end

    DevMachine -->|"docker pull"| Registry
    DevMachine -->|"docker run"| DockerEngine
    DockerEngine --> DockerImage
    DockerImage --> Entrypoint
    Entrypoint -->|"calls"| SetupScript
    SetupScript --> Pyenv
    SetupScript --> NvmRustGo
    Entrypoint --> RubyBunJava
    DockerEngine -.->|"mount"| Workspace
    DockerEngine -.->|"env vars CODEX_ENV_*"| SetupScript

    %% Documentation & Licensing
    subgraph "Project Files"  
        direction TB
        README["README.md"]:::docs
        Gitignore[".gitignore"]:::docs
        LicensesDir["LICENSES/"]:::docs
        SBOM1["codex-universal-image-sbom.spdx.json"]:::docs
        SBOM2["codex-universal-image-sbom.md"]:::docs
        LicenseFile["LICENSE"]:::docs
    end

    %% Click Events
    click BuildImageYML "https://github.com/openai/codex-universal/blob/main/.github/workflows/build-image.yml"
    click DockerfileNode "https://github.com/openai/codex-universal/tree/main/Dockerfile"
    click Entrypoint "https://github.com/openai/codex-universal/blob/main/entrypoint.sh"
    click SetupScript "https://github.com/openai/codex-universal/blob/main/setup_universal.sh"
    click README "https://github.com/openai/codex-universal/blob/main/README.md"
    click LicensesDir "https://github.com/openai/codex-universal/tree/main/LICENSES/"
    click SBOM1 "https://github.com/openai/codex-universal/blob/main/LICENSES/codex-universal-image-sbom.spdx.json"
    click SBOM2 "https://github.com/openai/codex-universal/blob/main/LICENSES/codex-universal-image-sbom.md"
    click LicenseFile "https://github.com/openai/codex-universal/tree/main/LICENSES/LICENSE"
    click Gitignore "https://github.com/openai/codex-universal/blob/main/.gitignore"

    %% Styles
    classDef build fill:#cfe2f3,stroke:#084298,stroke-width:1px
    classDef runtime fill:#d1e7dd,stroke:#0f5132,stroke-width:1px
    classDef docs fill:#fff3cd,stroke:#664d03,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#41464b,stroke-width:1px
```
