Skip to content

Commit be649bd

Browse files
bryant-ungbryant-ung
committed
Initial commit: OpenAI Codex Docker container
- Dockerfile with Node 22 slim base and Codex CLI - docker-compose.yml for easy local running - Entrypoint script with config initialization - OAuth callback port exposure (1455) - GitHub Actions workflow for multi-arch builds - Comprehensive README with usage examples MIT License
0 parents  commit be649bd

9 files changed

Lines changed: 461 additions & 0 deletions

File tree

‎.dockerignore‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Git
2+
.git
3+
.gitignore
4+
5+
# Documentation
6+
README.md
7+
LICENSE
8+
9+
# Environment files
10+
.env
11+
.env.*
12+
13+
# Workspace
14+
workspace/
15+
16+
# GitHub
17+
.github/
18+
19+
# OS
20+
.DS_Store
21+
Thumbs.db

‎.env.example‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# OpenAI API Key (get one at https://platform.openai.com/api-keys)
2+
OPENAI_API_KEY=your-api-key-here
3+
4+
# Optional: OpenAI organization ID
5+
# OPENAI_ORG_ID=org-...
6+
7+
# Optional: Custom API base URL
8+
# OPENAI_API_BASE=https://api.openai.com/v1

‎.github/workflows/docker-publish.yml‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
name: Build and Push Docker Image
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
tags:
8+
- 'v*'
9+
pull_request:
10+
branches:
11+
- main
12+
13+
env:
14+
REGISTRY: docker.io
15+
IMAGE_NAME: ungb/codex
16+
17+
jobs:
18+
build-and-push:
19+
runs-on: ubuntu-latest
20+
permissions:
21+
contents: read
22+
packages: write
23+
24+
steps:
25+
- name: Checkout repository
26+
uses: actions/checkout@v4
27+
28+
- name: Set up QEMU
29+
uses: docker/setup-qemu-action@v3
30+
31+
- name: Set up Docker Buildx
32+
uses: docker/setup-buildx-action@v3
33+
34+
- name: Log in to Docker Hub
35+
if: github.event_name != 'pull_request'
36+
uses: docker/login-action@v3
37+
with:
38+
username: ${{ secrets.DOCKERHUB_USERNAME }}
39+
password: ${{ secrets.DOCKERHUB_TOKEN }}
40+
41+
- name: Extract metadata
42+
id: meta
43+
uses: docker/metadata-action@v5
44+
with:
45+
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
46+
tags: |
47+
type=ref,event=branch
48+
type=semver,pattern={{version}}
49+
type=semver,pattern={{major}}.{{minor}}
50+
type=raw,value=latest,enable={{is_default_branch}}
51+
52+
- name: Build and push
53+
uses: docker/build-push-action@v5
54+
with:
55+
context: .
56+
platforms: linux/amd64,linux/arm64
57+
push: ${{ github.event_name != 'pull_request' }}
58+
tags: ${{ steps.meta.outputs.tags }}
59+
labels: ${{ steps.meta.outputs.labels }}
60+
cache-from: type=gha
61+
cache-to: type=gha,mode=max

‎.gitignore‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Environment files
2+
.env
3+
.env.local
4+
5+
# Workspace directory (user's code)
6+
workspace/
7+
8+
# OS files
9+
.DS_Store
10+
Thumbs.db
11+
12+
# IDE
13+
.idea/
14+
.vscode/
15+
*.swp
16+
*.swo

‎Dockerfile‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
FROM node:22-slim
2+
3+
LABEL maintainer="ungb"
4+
LABEL description="OpenAI Codex CLI in a Docker container"
5+
LABEL org.opencontainers.image.source="https://github.com/ungb/codex-docker"
6+
7+
# Install system dependencies
8+
RUN apt-get update && apt-get install -y --no-install-recommends \
9+
git \
10+
curl \
11+
openssh-client \
12+
ca-certificates \
13+
jq \
14+
&& rm -rf /var/lib/apt/lists/*
15+
16+
# Install OpenAI Codex CLI globally
17+
RUN npm install -g @openai/codex
18+
19+
# Create non-root user for security
20+
RUN useradd -m -s /bin/bash coder \
21+
&& mkdir -p /home/coder/.codex \
22+
&& chown -R coder:coder /home/coder
23+
24+
# Set up workspace directory
25+
RUN mkdir -p /workspace && chown coder:coder /workspace
26+
27+
# Copy entrypoint script
28+
COPY --chown=coder:coder entrypoint.sh /entrypoint.sh
29+
RUN chmod +x /entrypoint.sh
30+
31+
# Switch to non-root user
32+
USER coder
33+
WORKDIR /workspace
34+
35+
# Environment variables
36+
ENV HOME=/home/coder
37+
ENV CODEX_CONFIG_DIR=/home/coder/.codex
38+
39+
# Expose OAuth callback port
40+
EXPOSE 1455
41+
42+
ENTRYPOINT ["/entrypoint.sh"]
43+
CMD ["codex"]

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# Codex Docker
2+
3+
Run [OpenAI Codex CLI](https://github.com/openai/codex) in a Docker container. Codex is OpenAI's lightweight coding agent that runs in your terminal.
4+
5+
## Quick Start
6+
7+
```bash
8+
# Pull and run (replace with your API key)
9+
docker run -it --rm \
10+
-v $(pwd):/workspace \
11+
-e OPENAI_API_KEY=your-key \
12+
ungb/codex
13+
```
14+
15+
## Prerequisites
16+
17+
- [Docker](https://docs.docker.com/get-docker/) installed
18+
- [OpenAI API key](https://platform.openai.com/api-keys) or ChatGPT account for OAuth
19+
20+
## Usage
21+
22+
### Using Docker Run
23+
24+
```bash
25+
# Basic usage with API key
26+
docker run -it --rm \
27+
-v $(pwd):/workspace \
28+
-e OPENAI_API_KEY=$OPENAI_API_KEY \
29+
ungb/codex
30+
31+
# With persistent config (remembers settings between runs)
32+
docker run -it --rm \
33+
-v $(pwd):/workspace \
34+
-v codex-config:/home/coder/.codex \
35+
-e OPENAI_API_KEY=$OPENAI_API_KEY \
36+
ungb/codex
37+
38+
# With git/ssh support
39+
docker run -it --rm \
40+
-v $(pwd):/workspace \
41+
-v codex-config:/home/coder/.codex \
42+
-v ~/.ssh:/home/coder/.ssh:ro \
43+
-v ~/.gitconfig:/home/coder/.gitconfig:ro \
44+
-e OPENAI_API_KEY=$OPENAI_API_KEY \
45+
ungb/codex
46+
```
47+
48+
### Using Docker Compose
49+
50+
1. Clone this repo or copy `docker-compose.yml` to your project:
51+
52+
```bash
53+
curl -O https://raw.githubusercontent.com/ungb/codex-docker/main/docker-compose.yml
54+
```
55+
56+
2. Create a `.env` file with your API key:
57+
58+
```bash
59+
echo "OPENAI_API_KEY=your-key-here" > .env
60+
```
61+
62+
3. Run:
63+
64+
```bash
65+
docker compose run --rm codex
66+
```
67+
68+
### Run a Specific Command
69+
70+
```bash
71+
# Run codex with arguments
72+
docker run -it --rm \
73+
-v $(pwd):/workspace \
74+
-e OPENAI_API_KEY=$OPENAI_API_KEY \
75+
ungb/codex \
76+
codex "explain this codebase"
77+
78+
# Check version
79+
docker run -it --rm ungb/codex codex --version
80+
81+
# Run with full auto-approve (be careful!)
82+
docker run -it --rm \
83+
-v $(pwd):/workspace \
84+
-e OPENAI_API_KEY=$OPENAI_API_KEY \
85+
ungb/codex \
86+
codex --full-auto "fix the tests"
87+
```
88+
89+
## Authentication
90+
91+
### Option 1: API Key (Recommended for Docker)
92+
93+
Get an API key from [OpenAI Platform](https://platform.openai.com/api-keys) and pass it as an environment variable:
94+
95+
```bash
96+
-e OPENAI_API_KEY=sk-...
97+
```
98+
99+
### Option 2: ChatGPT OAuth Login
100+
101+
For browser-based OAuth, expose port 1455 for the callback:
102+
103+
```bash
104+
docker run -it --rm \
105+
-p 1455:1455 \
106+
-v $(pwd):/workspace \
107+
-v codex-config:/home/coder/.codex \
108+
ungb/codex \
109+
codex login
110+
```
111+
112+
Or use host network mode:
113+
114+
```bash
115+
docker run -it --rm \
116+
--network host \
117+
-v $(pwd):/workspace \
118+
-v codex-config:/home/coder/.codex \
119+
ungb/codex \
120+
codex login
121+
```
122+
123+
## Volume Mounts
124+
125+
| Mount | Purpose |
126+
|-------|---------|
127+
| `/workspace` | Your project directory (required) |
128+
| `/home/coder/.codex` | Codex config and cache (optional, for persistence) |
129+
| `/home/coder/.ssh` | SSH keys for git operations (optional, read-only) |
130+
| `/home/coder/.gitconfig` | Git configuration (optional, read-only) |
131+
132+
## Environment Variables
133+
134+
| Variable | Required | Description |
135+
|----------|----------|-------------|
136+
| `OPENAI_API_KEY` | Yes* | Your OpenAI API key |
137+
| `OPENAI_ORG_ID` | No | OpenAI organization ID |
138+
| `OPENAI_API_BASE` | No | Custom API endpoint (for proxies) |
139+
140+
*Required unless using OAuth login
141+
142+
## Ports
143+
144+
| Port | Purpose |
145+
|------|---------|
146+
| 1455 | OAuth callback for `codex login` |
147+
148+
## Building Locally
149+
150+
```bash
151+
git clone https://github.com/ungb/codex-docker.git
152+
cd codex-docker
153+
docker build -t codex .
154+
```
155+
156+
## Troubleshooting
157+
158+
### Permission Denied on Mounted Files
159+
160+
The container runs as user `coder` (UID 1000). If you have permission issues:
161+
162+
```bash
163+
# Run with your user ID
164+
docker run -it --rm \
165+
--user $(id -u):$(id -g) \
166+
-v $(pwd):/workspace \
167+
-e OPENAI_API_KEY=$OPENAI_API_KEY \
168+
ungb/codex
169+
```
170+
171+
### Git Operations Failing
172+
173+
Ensure SSH keys are mounted and git is configured:
174+
175+
```bash
176+
docker run -it --rm \
177+
-v $(pwd):/workspace \
178+
-v ~/.ssh:/home/coder/.ssh:ro \
179+
-v ~/.gitconfig:/home/coder/.gitconfig:ro \
180+
-e OPENAI_API_KEY=$OPENAI_API_KEY \
181+
ungb/codex
182+
```
183+
184+
### OAuth Login Not Working
185+
186+
Ensure port 1455 is exposed:
187+
188+
```bash
189+
docker run -it --rm \
190+
-p 1455:1455 \
191+
-v $(pwd):/workspace \
192+
-v codex-config:/home/coder/.codex \
193+
ungb/codex \
194+
codex login
195+
```
196+
197+
## Sandbox Mode
198+
199+
Codex supports running in sandbox mode using Docker. When you run Codex inside this container, it's already isolated. For nested Docker support (Docker-in-Docker), mount the Docker socket:
200+
201+
```bash
202+
docker run -it --rm \
203+
-v $(pwd):/workspace \
204+
-v /var/run/docker.sock:/var/run/docker.sock \
205+
-e OPENAI_API_KEY=$OPENAI_API_KEY \
206+
ungb/codex
207+
```
208+
209+
## License
210+
211+
MIT License - see [LICENSE](LICENSE)
212+
213+
## Links
214+
215+
- [Codex CLI Documentation](https://github.com/openai/codex)
216+
- [OpenAI Platform](https://platform.openai.com/)
217+
- [OpenAI API Keys](https://platform.openai.com/api-keys)

0 commit comments

Comments
 (0)