convez.ai
AgenteDevOps & InfraestruturaAvançado
ycpss91255-docker

Contêiner AI Agent com DinD

ycpss91255-docker/ai_agent

DinD dev container com Claude, Gemini e Codex pré-instalados

Ver no GitHub
InicialPluginScore · de 0 a 100

Ambiente 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_agent

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 5 meses
Versão
v2.0.0
Issues abertas
8
Contribuidores
1

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

CI License

CI

English | 繁體中文 | 简体中文 | 日本語

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

./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: .env and .env.gpg are 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 (not docker_*), so detection falls through to .env.example which has IMAGE_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 pull may 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.

VariableDescription
USER_NAME / USER_UID / USER_GIDContainer user matching host (auto-detected)
GPU_ENABLEDAuto-detected, drives BASE_IMAGE and GPU_VARIANT
BASE_IMAGEnode:20-slim (CPU) or nvidia/cuda:13.1.1-cudnn-devel-ubuntu24.04 (GPU)
WS_PATHHost path mounted to ~/work inside container
IMAGE_NAMEDocker 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

StagePurpose
sysUser/group creation, locale, timezone, Node.js (GPU only)
baseDev tools, Python, build tools, Docker, jq, ripgrep
develClaude Code, Gemini CLI, Codex CLI, entrypoint, non-root user
testBats smoke tests (ephemeral, discarded after verification)

Compose Services

ServiceDescription
develCPU variant (default)
devel-gpuGPU variant with NVIDIA device reservation
testSmoke test (profile-gated)

Entrypoint Flow

  1. Start dockerd (DinD) via sudo, wait until ready (up to 30s)
  2. Copy OAuth credentials from read-only mount into data/ directory (first run only)
  3. Decrypt .env.gpg and export API keys as environment variables (if present)
  4. Execute CMD (bash)

Pre-installed Tools

ToolPurpose
Claude CodeAnthropic AI CLI
Gemini CLIGoogle AI CLI
Codex CLIOpenAI AI CLI
Docker (DinD)Isolated Docker daemon inside container
Node.js 20Runtime for CLI tools
Python 3Scripting and development
git, curl, wgetVersion control and downloads
jq, ripgrepJSON processing and code search
make, g++, cmakeBuild toolchain
treeDirectory 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.

Ver o original no GitHub

Bom para

Relacionados