Contêiner AI Agent com DinD
ycpss91255-docker/ai_agent
DinD dev container com Claude, Gemini e Codex pré-instalados
Ver no GitHubAmbiente de desenvolvimento Docker-in-Docker pré-configurado com Claude Code, Gemini CLI e OpenAI Codex CLI. Suporta variantes CPU e GPU (NVIDIA), executa como usuário não-root com UID/GID do host, e persiste credenciais OAuth e conversas localmente.
Instalação
npx convez-ai ycpss91255-docker/ai_agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Desenvolvimento local isolado com múltiplos agentes de IA
- Integração de Claude Code, Gemini CLI e Codex em pipelines Docker
- Ambientes de teste e prototipagem com credenciais persistidas
Veredito

Solução robusta e bem-arquitetada para desenvolvimento local com múltiplos CLIs de IA em contêiner isolado. Requer conhecimento sólido de Docker e CLI tools, mas oferece setup declarativo e reproduzível com segurança por GPG e suporte GPU nativo.
README
A tradução para o português deste README ainda está na fila.
AI Agent Dev Environment
Docker-in-Docker (DinD) development container for AI agents, with Claude Code, Gemini CLI, and OpenAI Codex CLI pre-installed. Available in CPU and NVIDIA GPU variants. Runs as non-root user with host UID/GID matching.
Table of Contents
- TL;DR
- Overview
- Prerequisites
- Quick Start
- Conversation Persistence
- Running Multiple Instances
- Authentication
- Usage as Subtree
- Configuration
- Smoke Tests
- Architecture
TL;DR
./build.sh && ./run.sh # Build and run (CPU, default)
- Isolated Docker-in-Docker container with Claude Code + Gemini CLI + OpenAI Codex CLI
- Non-root user, auto-detected UID/GID from host
- OAuth credentials auto-copied on first run, conversations persisted locally
- Optionally encrypted API keys (GPG AES-256)
- CPU default, GPU via
./run.sh devel-gpu
Overview
graph TB
subgraph Host
H_OAuth["~/.claude & ~/.gemini & ~/.codex<br/>(OAuth credentials)"]
H_WS["Workspace<br/>(WS_PATH)"]
H_Data["Data Directory<br/>(agent_* or ./data/)"]
end
subgraph "Container (DinD)"
EP["entrypoint.sh"]
DinD["dockerd<br/>(isolated)"]
Claude["Claude Code"]
Gemini["Gemini CLI"]
Codex["Codex CLI"]
Tools["git, python3, jq,<br/>ripgrep, make, cmake..."]
EP -->|"1. start"| DinD
EP -->|"2. copy credentials<br/>(first run)"| Claude
EP -->|"2."| Gemini
EP -->|"2."| Codex
EP -->|"3. decrypt API keys<br/>(if .env.gpg)"| Tools
end
H_OAuth -->|"read-only mount"| EP
H_WS -->|"bind mount<br/>~/work"| Tools
H_Data -->|"bind mount<br/>~/.claude, ~/.gemini,<br/>~/.codex"| Claude
H_Data -->|"bind mount"| Gemini
H_Data -->|"bind mount"| Codex
graph LR
subgraph "Dockerfile Stages"
sys["sys<br/>user, locale, tz"]
base["base<br/>dev tools, docker"]
devel["devel<br/>claude, gemini, codex"]
test["test<br/>bats smoke test"]
end
sys --> base --> devel --> test
subgraph "Compose Services"
S_CPU["devel<br/>(CPU, default)"]
S_GPU["devel-gpu<br/>(NVIDIA GPU)"]
S_Test["test<br/>(ephemeral)"]
end
devel -.-> S_CPU
devel -.-> S_GPU
test -.-> S_Test
flowchart LR
subgraph "run.sh"
A["Generate .env<br/>(template)"] --> B["Derive BASE_IMAGE<br/>(post_setup.sh)"]
B --> C{"--data-dir?"}
C -->|yes| D["Use specified dir"]
C -->|no| E{"agent_* found?"}
E -->|yes| F["Use agent_* dir"]
E -->|no| G["Use ./data/"]
D --> H["docker compose run"]
F --> H
G --> H
end
Prerequisites
- Docker with Compose V2
- GPU variant requires nvidia-container-toolkit
- Host-side OAuth login for Claude Code (
claude), Gemini CLI (gemini), and/or Codex CLI (codex)
Quick Start
# Build (auto-generates .env on every run)
./build.sh # CPU variant (default)
./build.sh devel-gpu # GPU variant
./build.sh --no-env test # Build without refreshing .env
# Run
./run.sh # CPU variant (default)
./run.sh devel-gpu # GPU variant
./run.sh --data-dir ../agent_foo # Specify data directory
./run.sh --no-env -d # Background start, skip .env refresh
# Exec into running container
./exec.sh
Conversation Persistence
Conversation history and session data are persisted via bind mount, surviving container restarts.
run.sh automatically scans upward from the project directory for an agent_* directory. If found, data is stored there; otherwise it falls back to ./data/.
# Example: if ../agent_myproject/ exists
../agent_myproject/
├── .claude/ # Claude Code conversations, settings, session
├── .gemini/ # Gemini CLI conversations, settings, session
└── .codex/ # Codex CLI conversations, settings, session
# Fallback: no agent_* directory found
./data/
├── .claude/
├── .gemini/
└── .codex/
- First startup: OAuth credentials are copied from the host into the data directory
- Subsequent startups: data directory already has data and is used directly (no overwrite)
- You can freely copy, backup, or move the data directory
- Override manually:
./run.sh --data-dir /path/to/dir
Running Multiple Instances
Use --project-name (-p) to create fully isolated instances, each with its own named volumes:
# Instance 1
docker compose -p ai1 --env-file .env run --rm devel
# Instance 2 (in another terminal)
docker compose -p ai2 --env-file .env run --rm devel
# Instance 3
docker compose -p ai3 --env-file .env run --rm devel
For multiple instances, create separate agent_* directories:
mkdir ../agent_proj1 ../agent_proj2
./run.sh --data-dir ../agent_proj1
./run.sh --data-dir ../agent_proj2
Credentials, conversations, and session data are fully isolated. To clean up, simply delete the directory:
rm -rf ../agent_proj1
Authentication
Two methods are supported. Both can be used at the same time.
OAuth (Interactive Login)
For interactive CLI usage. Log in on the host first:
claude # Log in to Claude Code
gemini # Log in to Gemini CLI
codex # Log in to Codex CLI
Credentials (~/.claude, ~/.gemini, ~/.codex) are mounted read-only into the container and copied into the data directory on first startup. Subsequent startups reuse the existing data.
API Key (Encrypted)
For programmatic API access. Keys are stored encrypted with GPG (AES-256), never in plaintext.
# 1. Create plaintext .env
cat <<EOF > .env.keys
ANTHROPIC_API_KEY=sk-ant-xxxxx
GEMINI_API_KEY=xxxxx
OPENAI_API_KEY=sk-xxxxx
EOF
# 2. Encrypt (you will be prompted to set a passphrase)
encrypt_env.sh # available inside container, or ./encrypt_env.sh on host
# 3. Remove plaintext
rm .env.keys
On container startup, if .env.gpg is detected in the workspace, you will be prompted for the passphrase. Decrypted keys are only held in memory as environment variables.
Note:
.envand.env.gpgare already in.gitignore.
Usage as Subtree
This repo can be embedded into another project via git subtree, letting the project carry its own Docker dev environment.
Adding to Your Project
git subtree add --prefix=docker/ai_agent \
https://github.com/ycpss91255-docker/ai_agent.git main --squash
Example directory structure after adding:
my_project/
├── src/ # Project source code
├── docker/ai_agent/ # Subtree
│ ├── build.sh
│ ├── run.sh
│ ├── compose.yaml
│ ├── Dockerfile
│ └── .base/
└── ...
Building and Running
cd docker/ai_agent
./build.sh && ./run.sh
build.sh uses --base-path internally, so path detection works correctly regardless of where you run it from.
Workspace Detection
When the subtree sits at my_project/docker/ai_agent/:
- IMAGE_NAME: directory name is
ai_agent(notdocker_*), so detection falls through to.env.examplewhich hasIMAGE_NAME=ai_agent— works correctly. - WS_PATH: strategy 1 (sibling scan) and strategy 2 (path traversal) may not match, so strategy 3 (fallback) resolves to the parent directory (
my_project/docker/).
Recommendation: after the first build, edit WS_PATH in .env to point to your actual workspace. The value is preserved on subsequent builds.
Syncing with Upstream
git subtree pull --prefix=docker/ai_agent \
https://github.com/ycpss91255-docker/ai_agent.git main --squash
Notes:
- Local modifications are tracked by git normally.
subtree pullmay produce merge conflicts if upstream changed the same files you modified locally.- Do not modify
.base/inside the subtree — it is managed by the env repo's own subtree.
Configuration
.env is auto-generated on every build.sh / run.sh invocation (pass --no-env to skip). See .env.example for details.
| Variable | Description |
|---|---|
USER_NAME / USER_UID / USER_GID | Container user matching host (auto-detected) |
GPU_ENABLED | Auto-detected, drives BASE_IMAGE and GPU_VARIANT |
BASE_IMAGE | node:20-slim (CPU) or nvidia/cuda:13.1.1-cudnn-devel-ubuntu24.04 (GPU) |
WS_PATH | Host path mounted to ~/work inside container |
IMAGE_NAME | Docker image name (default: ai_agent) |
Smoke Tests
See TEST.md for details.
Architecture
ai_agent/
├── Dockerfile # Multi-stage build (sys -> base -> devel -> test)
├── compose.yaml # Services: devel (CPU), devel-gpu, test
├── build.sh -> .base/script/docker/build.sh # Symlink
├── run.sh -> .base/script/docker/run.sh # Symlink
├── exec.sh -> .base/script/docker/exec.sh # Symlink
├── stop.sh -> .base/script/docker/stop.sh # Symlink
├── Makefile -> .base/script/docker/Makefile # Symlink
├── encrypt_env.sh # Helper to encrypt API keys
├── post_setup.sh # Derives BASE_IMAGE from GPU_ENABLED
├── .env.example # IMAGE_NAME fallback
├── setup.conf # Repo override of .base/setup.conf
├── script/
│ └── entrypoint.sh # DinD startup, OAuth copy, API key decryption
├── test/
│ └── smoke/
│ └── agent_env.bats # Bats smoke tests (repo-specific)
├── doc/ # Translated READMEs
│ ├── README.zh-TW.md
│ ├── README.zh-CN.md
│ └── README.ja.md
├── .base/ # Shared scripts, tests, CI (git subtree)
├── .github/workflows/
│ └── main.yaml # CI/CD (calls template reusable workflows)
└── README.md
Dockerfile Stages
| Stage | Purpose |
|---|---|
sys | User/group creation, locale, timezone, Node.js (GPU only) |
base | Dev tools, Python, build tools, Docker, jq, ripgrep |
devel | Claude Code, Gemini CLI, Codex CLI, entrypoint, non-root user |
test | Bats smoke tests (ephemeral, discarded after verification) |
Compose Services
| Service | Description |
|---|---|
devel | CPU variant (default) |
devel-gpu | GPU variant with NVIDIA device reservation |
test | Smoke test (profile-gated) |
Entrypoint Flow
- Start
dockerd(DinD) via sudo, wait until ready (up to 30s) - Copy OAuth credentials from read-only mount into
data/directory (first run only) - Decrypt
.env.gpgand export API keys as environment variables (if present) - Execute CMD (
bash)
Pre-installed Tools
| Tool | Purpose |
|---|---|
| Claude Code | Anthropic AI CLI |
| Gemini CLI | Google AI CLI |
| Codex CLI | OpenAI AI CLI |
| Docker (DinD) | Isolated Docker daemon inside container |
| Node.js 20 | Runtime for CLI tools |
| Python 3 | Scripting and development |
| git, curl, wget | Version control and downloads |
| jq, ripgrep | JSON processing and code search |
| make, g++, cmake | Build toolchain |
| tree | Directory visualization |
GPU variant additionally includes: CUDA 13.1.1, cuDNN, OpenCL, Vulkan.
Container Capabilities
Both services require SYS_ADMIN, NET_ADMIN, MKNOD capabilities with seccomp:unconfined for DinD to function. The inner Docker daemon is fully isolated from the host.