Dev Agent Shell (Docker)

A reproducible “everything-in-one” development container built to run agentic CLI tools (Codex, Gemini CLI, Claude Code) alongside a full multi-language toolchain (Node/Java/PHP/Python/Perl/C/C++) plus Android + GIS + document/image utilities.

The container is intentionally configured to run as root (“yolo mode”) so you can install extra packages, tweak the environment, and let agents perform system-level tasks without friction. If anything gets messy, you can always revert by rebuilding the image from scratch.

---

What’s in this repo

• Dockerfile — builds the image (toolchain + agent CLIs)
• docker-compose.yml — runs a long-lived interactive container with persisted agent auth/config

---

Why this exists

Agentic CLIs (and humans working with them) tend to need a grab-bag of capabilities:

• Clone repos, edit files, run builds/tests, generate patches
• Parse and transform PDFs, images, spreadsheets, and archives
• Compile native code and build polyglot projects
• Work with Android projects (Gradle + SDK tooling)
• Run GIS conversions and geoprocessing (GDAL/OGR)
• Persist logins/settings across container rebuilds

This image packages those capabilities in one place, reproducibly.

---

Included agents and how they’re installed

These are installed globally via npm:

• OpenAI Codex CLI (codex)
• Google Gemini CLI (gemini)
• Claude Code (claude)

Usage is interactive: you exec into the container and run the agent you want.

Example inside the container:

codex --help
gemini --help
claude --help

---

Toolchain & utilities included

Core dev/runtime languages

• Node.js (base image)
• Java (JDK 17) — required for Gradle/Android builds and many JVM projects
• PHP 8.2 + Composer — common PHP development stack
• Python 3 + pip — scripting, data processing, automation
• Perl + cpanminus — legacy tooling/scripts
• C/C++ build stack — compilers and build systems for native builds

Build and debugging tools

• build-essential, cmake, ninja, pkg-config
• gdb, strace

Repo / shell productivity

• git, git-lfs, openssh-client
• jq, ripgrep, fd (Debian package: fd-find), tree, less, bash-completion
• procps, htop

Documents / OCR / spreadsheets

• PDF: poppler-utils (e.g., pdftotext, pdfinfo, pdftoppm), qpdf
• OCR: tesseract-ocr
• Excel-ish: gnumeric (includes ssconvert)

Image processing / conversion

• imagemagick, graphicsmagick, libvips-tools
• Optimizers: jpegoptim, optipng, pngquant, gifsicle, webp
• Metadata/inspection: exiftool
• Vector graphics: inkscape
• Media: ffmpeg

Android development

• Gradle + Kotlin
• Android command-line tools (sdkmanager)
• Baseline SDK components (platform-tools / build-tools / platform)

GIS / geoprocessing

• gdal-bin (GDAL/OGR CLI: gdalinfo, ogr2ogr, gdalwarp, etc.)
• proj-bin, geos-bin
• spatialite-bin, sqlite3
• Optional OSM utilities (if present in your Dockerfile): osmctools, osmosis

---

Running as root (“yolo mode”)

This container intentionally runs as root so:

• Agents can install packages (apt/pip/npm) when needed
• You can debug/patch environments quickly
• Build systems that expect system-wide installs “just work”

Trade-off: root has full control inside the container and any mounted directories. Use responsibly.

If something breaks, you can revert instantly by rebuilding the container (see below).

---

Persisting agent logins & settings

Agent CLIs store credentials and settings in root’s home directory. To avoid re-authing on every rebuild, docker-compose.yml persists these paths via named volumes (Docker-managed storage):

• Claude Code: /root/.claude
• Gemini CLI: /root/.gemini
• Codex CLI: /root/.codex

Persisting single config files (Windows note)

If you ever need to persist a single file (e.g., .../something.json) on Windows, prefer a host bind mount to an existing file. If the host path doesn’t exist as a file at container start, Docker may create a directory and break tools that expect a file.

Resetting auth/settings

To wipe all persisted logins and start clean:

docker compose down -v
docker compose up -d --build

---

Quickstart

1) Build and start

docker compose up -d --build

2) Enter the shell

docker compose exec codex bash

3) Check tools

codex --version || true
gemini --version || true
claude --version || true

java -version
gradle -v
python3 --version
php -v
composer -V
gdalinfo --version

---

Typical workflows

Run an agent against a mounted project

Mount your project into /app/... in docker-compose.yml, then:

docker compose exec codex bash
cd /app/your-project
codex
# or:
gemini
# or:
claude

Android builds

Inside the container, in an Android project directory:

./gradlew assemble
./gradlew lint

If a tool complains about JAVA_HOME, set it once in the shell:

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH="$PATH:$JAVA_HOME/bin"

---

“Undo everything” (clean rebuild)

Rebuild image without cache:

docker compose build --no-cache
docker compose up -d

Also remove persisted volumes (full reset):

docker compose down -v
docker compose up -d --build