Codex + Docker + Git Worktree: Containerized Parallel Development

OpenAI Codex runs agents inside sandboxed containers. By combining Docker with git worktree, you can mount separate worktrees into individual Codex containers, giving each agent its own branch and full filesystem isolation.

Why Codex + Docker + Worktrees?

Codex agents execute code inside containers for sandboxing and reproducibility. Git worktrees add branch-level isolation on top of container isolation. Together, you get:

No file conflicts: Each container mounts a different worktree, so agents never touch the same files.
Shared git history: All worktrees share the same repository, so branches and commits are immediately visible everywhere.
Reproducible environments: Docker ensures identical dependencies, tools, and runtimes for every agent.
Easy cleanup: Remove the container and the worktree, and everything is gone.

Setup: Worktrees for Docker Containers

First, create worktrees for each task you want to run in parallel:

Create worktrees for each agent

# Create worktrees for parallel Codex agents
git worktree add -b agent/refactor-api ../project-agent-1 main
git worktree add -b agent/add-tests ../project-agent-2 main
git worktree add -b agent/fix-docs ../project-agent-3 main

# Verify
git worktree list

Docker Compose with Worktree Mounts

A linked worktree contains a .git file(not a directory) that points back to shared metadata in the main repository's .git/worktrees/ directory. For Git commands to work inside a container, the container must be able to follow this pointer. The simplest approach is to mount the parent directory so the path layout is preserved:

docker-compose.agents.yml

# docker-compose.agents.yml
#
# Assumes worktrees were created as siblings:
#   /home/user/project/           ← main repo (.git/ directory here)
#   /home/user/project-agent-1/   ← linked worktree
#   /home/user/project-agent-2/   ← linked worktree
#   /home/user/project-agent-3/   ← linked worktree
#
# We mount the parent so each container can resolve the .git pointer.

services:
  agent-1:
    build: .   # Your Dockerfile with Codex + project dependencies
    volumes:
      - /home/user:/home/user   # Preserve full path layout
    working_dir: /home/user/project-agent-1
    environment:
      - TASK=refactor the API layer to use repository pattern

  agent-2:
    build: .
    volumes:
      - /home/user:/home/user
    working_dir: /home/user/project-agent-2
    environment:
      - TASK=add unit tests for the auth module

  agent-3:
    build: .
    volumes:
      - /home/user:/home/user
    working_dir: /home/user/project-agent-3
    environment:
      - TASK=fix documentation for the REST API

Important: Do not mount the main repo's .git directory on top of a worktree's .git file. A linked worktree's .git is a pointer file, not a directory, and overwriting it breaks worktree isolation. Mount the parent directory (or use bind mounts that preserve the full path layout) so Git can follow the pointer naturally.

Running the Agents

Launch and monitor agents

# Start all agents in parallel
docker compose -f docker-compose.agents.yml up

# Monitor progress
docker compose -f docker-compose.agents.yml logs -f

# When done, check what each agent produced
cd ../project-agent-1 && git log --oneline -3
cd ../project-agent-2 && git log --oneline -3
cd ../project-agent-3 && git log --oneline -3

Merging Agent Results

After the agents finish, review and merge each branch:

Push and create PRs

# Push each agent's branch
cd ../project-agent-1 && git push -u origin agent/refactor-api
cd ../project-agent-2 && git push -u origin agent/add-tests
cd ../project-agent-3 && git push -u origin agent/fix-docs

# Create PRs (or merge directly)
gh pr create --base main --head agent/refactor-api --title "refactor: repository pattern"
gh pr create --base main --head agent/add-tests --title "test: auth module coverage"
gh pr create --base main --head agent/fix-docs --title "docs: REST API documentation"

Cleanup

Full cleanup

# Stop and remove containers
docker compose -f docker-compose.agents.yml down

# Remove worktrees
cd ../project
git worktree remove ../project-agent-1
git worktree remove ../project-agent-2
git worktree remove ../project-agent-3

# Delete merged branches
git branch -d agent/refactor-api agent/add-tests agent/fix-docs

Tips

Pre-install Dependencies in the Docker Image

Bake npm install or your package manager into the Docker image so each container starts ready to work. This avoids each agent running its own install step and potentially conflicting.

Use .env Files Per Worktree

If agents need different environment variables (API keys, ports), place a separate .env file in each worktree directory. Docker Compose can reference these with env_file.

Resource Limits

Set CPU and memory limits in Docker Compose to prevent one agent from starving others. Three to four concurrent agents is a practical maximum on most developer machines.

Summary

Codex + Docker + git worktree gives you fully isolated, containerized AI agents that each work on their own branch. Docker provides runtime isolation and reproducibility, while worktrees provide git-level branch isolation. Together they enable safe, parallel, automated development at scale.