Base Image Customization

The default Codex Cloud sandbox image includes a minimal Linux distribution, common language runtimes (Node.js, Python, Go), and standard build tools (git, make, gcc). For many projects, this is sufficient. But when your project requires specific system libraries (libvips for image processing, ffmpeg for video, GDAL for geospatial), specific runtime versions (Node 18 vs 22, Python 3.11 vs 3.13), or proprietary tools (commercial compilers, licensed SDKs), the default image falls short. Custom base images let you bake these dependencies into the sandbox so every task starts with them pre-installed.

Custom images are defined as Dockerfiles that extend the Codex base image. You add your system packages, runtime versions, and tools. The image is built once, stored in a registry, and referenced in your Codex Cloud configuration. Every task that uses this image starts with your custom dependencies already installed — eliminating the install-at-boot-time overhead and ensuring version consistency across all tasks.

# Custom Codex sandbox image
FROM codex-base:latest

# System libraries for image processing
RUN apt-get update && apt-get install -y \
    libvips-dev \
    ffmpeg \
    imagemagick \
    && rm -rf /var/lib/apt/lists/*

# Specific Node.js version
RUN nvm install 22.0.0 && nvm alias default 22.0.0

# Python data science stack
RUN pip install numpy pandas scikit-learn matplotlib

# Project-specific CLI tools
RUN npm install -g @vercel/ncc turbo