Skip to content

docker.md

Latest commit

 

History

History
145 lines (100 loc) · 3.07 KB

docker.md

File metadata and controls

145 lines (100 loc) · 3.07 KB

Codex Agent Docker Image Setup

  • Path: docs/setup/ubuntu/docker.md
  • Template Version: 20260508

Purpose

This document describes the Codex agent Docker image that is built from this repository.

The image is used by GitHub Flows launch/profile configuration when a Codex-based handler must run in an isolated container.

This document covers only the image build and basic verification. It does not cover application deployment, Apache configuration, webhook setup, credentials, or per-run profile configuration.

Repository Contract

Dockerfile:

etc/docker/Dockerfile.codex

Recommended image tag:

github-flows-agent-codex:latest

The current Dockerfile:

  • uses node:20-bookworm-slim;
  • installs Git, GitHub CLI, CA certificates, OpenSSH client, and Codex CLI;
  • accepts UID and GID build arguments;
  • adjusts the bundled node user to the requested UID/GID;
  • uses /workspace as the working directory;
  • runs containers as the non-root node user.

The image does not define a default command. The execution command is supplied by GitHub Flows launch/profile configuration.

Build the Image

Build from the repository root:

docker build \
  -f etc/docker/Dockerfile.codex \
  --build-arg UID=$(id -u) \
  --build-arg GID=$(id -g) \
  -t github-flows-agent-codex:latest \
  .

Check that the image exists:

docker images github-flows-agent-codex

Verify the Image

Check the container user:

docker run --rm github-flows-agent-codex:latest whoami

Expected result:

node

Check the working directory:

docker run --rm github-flows-agent-codex:latest pwd

Expected result:

/workspace

Check the installed tools:

docker run --rm github-flows-agent-codex:latest bash -lc '
node -v
npm -v
codex --version
git --version
gh --version
ssh -V
'

Workspace Mount

GitHub Flows should mount a per-run workspace into the container at:

/workspace

Example manual check:

mkdir -p ./var/work/test-run

docker run --rm \
  --mount type=bind,src="$(pwd)/var/work/test-run",dst=/workspace \
  github-flows-agent-codex:latest \
  bash -lc 'pwd && echo test > check.txt && ls -lh check.txt'

Check the file on the host:

ls -lh ./var/work/test-run/check.txt
cat ./var/work/test-run/check.txt

Runtime Restrictions

The container should receive only the per-run workspace and the explicit credentials required by the selected launch/profile configuration.

Do not mount:

  • the runtime user's home directory;
  • SSH configuration directories;
  • general user configuration directories;
  • the application .env file;
  • the Docker socket.

Do not run the agent container with privileged host access.

Result

After this setup:

  • the image github-flows-agent-codex:latest exists locally;
  • the image is built from etc/docker/Dockerfile.codex;
  • the container runs as non-root user node;
  • /workspace is the container working directory;
  • GitHub Flows launch/profile configuration remains responsible for the runtime command, mounts, environment, and credentials.