Ejecuta herramientas CLI de IA en Docker o Podman de forma segura (Guía 2026)

Los agentes de programación con IA pueden escribir archivos, ejecutar comandos de shell y leer todo lo que tu cuenta de usuario puede alcanzar. Esta guía te muestra cómo ejecutar herramientas CLI de IA en Docker o Podman dentro de un entorno seguro y aislado, de modo que un rm -rf alucinado o una instalación de dependencias fallida no puedan tocar tu máquina. Construirás una única imagen de contenedor que aloja Claude Code, Amp, Factory.ai, Gemini CLI, OpenCode y GitHub Copilot CLI, cada una con sus propias configuraciones, claves API y montajes de proyectos.

La versión honesta del argumento: un contenedor es aislamiento, no una máquina virtual. Comparte tu kernel. Si montas tus claves SSH o el socket de Docker dentro, le has entregado tu host al agente de todos modos. Todo en esta guía está construido en torno a no hacer eso.

Si quieres la misma idea pero con el agente viviendo en un servidor en lugar de tu portátil, nuestra guía de despliegue de NanoClaw cubre un agente Claude aislado en contenedor en un VPS.

¿Por qué ejecutar herramientas CLI de IA en Docker o Podman? (aislamiento y sandbox)

Ejecutar agentes de programación con IA en sandbox mediante contenedores te da seis cosas:

Lo que los contenedores no te dan:

• Aislamiento de kernel. Una fuga del contenedor es un compromiso del host. Si necesitas una frontera de seguridad real, usa una VM (es la misma razón por la que ejecutamos código no confiable en VMs, no en contenedores).
• Protección de los datos montados. El agente puede borrar cualquier cosa dentro de los directorios que montes. Monta un directorio de proyecto, no un directorio de proyectos que no puedas permitirte perder.
• Protección frente a la red. El contenedor tiene salida a internet a menos que configures lo contrario. Un agente aún puede exfiltrar lo que pueda leer.

Requisitos previos: Docker Desktop o Podman Desktop

Elige un motor de contenedores. Docker si ya lo conoces, Podman si estás en Fedora o quieres rootless por defecto. Todo lo demás de esta guía funciona igual.

docker --version
docker compose version

Docker version 29.7.2, build ...
Docker Compose version v2.x.x

# Fedora/RHEL/CentOS
sudo dnf install podman podman-compose

# Ubuntu/Debian
sudo apt install podman podman-compose

# macOS (via Homebrew)
brew install podman podman-compose

podman machine init
podman machine start

podman --version
podman compose version
podman info --format '{{.Host.Security.Rootless}}'

Arquitectura del contenedor: la imagen base con Python y Node

Una imagen, dos runtimes. Casi todas las herramientas CLI de IA son un paquete de Node o un script de shell que además quiere Python para sus utilidades, y reconstruir esa pila por herramienta es tiempo perdido.

Usamos nikolaik/python-nodejs, que incluye:

¿Por qué Node 26 en lugar de Node 25? Node 25 era una línea impar, no LTS, y llegó a su fin de vida a mediados de 2026. Si construiste este contenedor desde una guía de 2025, tu imagen base está en un runtime EOL sin parches de seguridad. Esa es toda la razón para reconstruir.

El detalle del UID 1000 importa más de lo que parece. Como pn es UID 1000, los archivos que crea dentro de un ~/websites montado por bind quedan en propiedad del UID 1000 en tu host, que es tu usuario normal de Linux en la mayoría de las distribuciones. Si tu usuario del host no es 1000, lee la sección de permisos en la solución de problemas.

Paso 1: crea la estructura del proyecto

mkdir -p ~/docker-ai-tools ~/dev-home ~/websites
cd ~/docker-ai-tools

mkdir -p ~/podman-ai-tools ~/dev-home ~/websites
cd ~/podman-ai-tools

Para qué sirve cada directorio:

• ~/docker-ai-tools o ~/podman-ai-tools: los archivos de configuración del contenedor (Dockerfile, archivo compose, .env)
• ~/dev-home: el directorio home del usuario del contenedor, montado por bind. Guarda las configuraciones de las CLI, el estado de autenticación y las herramientas instaladas. Sobrevive a las reconstrucciones del contenedor.
• ~/websites: tus proyectos reales, montados por bind en el contenedor. Es lo único que el agente debería poder tocar.

sudo chown -R 1000:1000 ~/dev-home ~/websites

Paso 2: crea el Containerfile/Dockerfile

# Dockerfile
# Base image with Node.js 26, Python 3.14, and package managers
FROM nikolaik/python-nodejs:python3.14-nodejs26-bookworm

SHELL ["/bin/bash", "-c"]

# The image already has a non-root user "pn" (UID 1000)
USER root

# Install system dependencies first
RUN apt-get update && apt-get install -y --no-install-recommends \
    git \
    jq \
    curl \
    vim \
    nano \
    htop \
    tree \
    ripgrep \
    rsync \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Starship prompt system-wide
# This works even when /home/pn is bind-mounted from the host
RUN curl -sS https://starship.rs/install.sh | sh -s -- -y \
 && mkdir -p /opt/skeleton/.config \
 && starship preset catppuccin-powerline -o /opt/skeleton/.config/starship.toml

# Minimal Bash configuration with Starship
RUN cat > /opt/skeleton/.bashrc <<'BRC'
# Bash initialized for pn user
# Enable Node Corepack and Yarn
corepack enable >/dev/null 2>&1 || true
corepack prepare yarn@stable --activate >/dev/null 2>&1 || true

# Quality of life alias
alias python=python3

# Initialize Starship prompt
if command -v starship >/dev/null 2>&1; then
  eval "$(starship init bash)"
fi
BRC

# Entrypoint script to seed dotfiles on first run
RUN cat > /usr/local/bin/boot.sh <<'SH'
#!/usr/bin/env bash
set -euo pipefail

# Seed ~/.bashrc if missing (e.g. empty bind-mounted /home/pn)
if [ ! -f "/home/pn/.bashrc" ]; then
  cp /opt/skeleton/.bashrc /home/pn/.bashrc
fi

# Seed Starship config if missing
mkdir -p /home/pn/.config
if [ ! -f "/home/pn/.config/starship.toml" ]; then
  cp /opt/skeleton/.config/starship.toml /home/pn/.config/starship.toml
fi

# Default to interactive bash if no command was provided
if [ $# -eq 0 ]; then
  set -- bash
fi
exec "$@"
SH
RUN chmod +x /usr/local/bin/boot.sh

# Switch back to the non-root user
USER pn
WORKDIR /home/pn/app

ENTRYPOINT ["/usr/local/bin/boot.sh"]
CMD ["bash"]

# Containerfile
# Base image with Node.js 26, Python 3.14, and package managers
FROM nikolaik/python-nodejs:python3.14-nodejs26-bookworm

SHELL ["/bin/bash", "-c"]

# The image already has a non-root user "pn" (UID 1000)
USER root

# Install system dependencies first
RUN apt-get update && apt-get install -y --no-install-recommends \
    git \
    jq \
    curl \
    vim \
    nano \
    htop \
    tree \
    ripgrep \
    rsync \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Starship prompt system-wide
# This works even when /home/pn is bind-mounted from the host
RUN curl -sS https://starship.rs/install.sh | sh -s -- -y \
 && mkdir -p /opt/skeleton/.config \
 && starship preset catppuccin-powerline -o /opt/skeleton/.config/starship.toml

# Minimal Bash configuration with Starship
RUN cat > /opt/skeleton/.bashrc <<'BRC'
# Bash initialized for pn user
# Enable Node Corepack and Yarn
corepack enable >/dev/null 2>&1 || true
corepack prepare yarn@stable --activate >/dev/null 2>&1 || true

# Quality of life alias
alias python=python3

# Initialize Starship prompt
if command -v starship >/dev/null 2>&1; then
  eval "$(starship init bash)"
fi
BRC

# Entrypoint script to seed dotfiles on first run
RUN cat > /usr/local/bin/boot.sh <<'SH'
#!/usr/bin/env bash
set -euo pipefail

# Seed ~/.bashrc if missing (e.g. empty bind-mounted /home/pn)
if [ ! -f "/home/pn/.bashrc" ]; then
  cp /opt/skeleton/.bashrc /home/pn/.bashrc
fi

# Seed Starship config if missing
mkdir -p /home/pn/.config
if [ ! -f "/home/pn/.config/starship.toml" ]; then
  cp /opt/skeleton/.config/starship.toml /home/pn/.config/starship.toml
fi

# Default to interactive bash if no command was provided
if [ $# -eq 0 ]; then
  set -- bash
fi
exec "$@"
SH
RUN chmod +x /usr/local/bin/boot.sh

# Switch back to the non-root user
USER pn
WORKDIR /home/pn/app

ENTRYPOINT ["/usr/local/bin/boot.sh"]
CMD ["bash"]

Ejecutar como usuario no root con USER pn

La línea USER pn del final es la relevante para la seguridad. Todo lo instalado en tiempo de ejecución, cada archivo que el agente crea y cada proceso que el agente lanza se ejecuta como UID 1000 dentro del contenedor, no como root. Los pasos de instalación siguen usando USER root temporalmente porque necesitas root para ejecutar apt-get, pero la imagen final y el contenedor en ejecución son no root.

Eso importa para el sandbox porque la mayoría de las fugas de contenedores dependen de root dentro del contenedor más un bug del kernel o una mala configuración (un socket montado, un flag privilegiado, un --cap-add). Ejecutar como UID 1000 elimina el camino fácil.

Si quieres el recorrido en profundidad de lo que los usuarios no root dentro de los contenedores te protegen y de lo que no, tenemos una guía aparte sobre ejecutar un contenedor como usuario no root.

Dos excepciones que conviene conocer:

• Puertos por debajo de 1024. Un usuario no root no puede vincularlos dentro del contenedor. Los servidores de desarrollo que ejecutarías junto a un agente (3000, 4321, 5173, 8080) están todos por encima de 1024, así que rara vez molesta.
• Instalación de paquetes del sistema. apt-get install necesita root. Por eso la sección “instalar un comando que falta” más abajo usa docker exec --user root.

Qué hace este Containerfile

Paso 3: crea la configuración de Compose

services:
  ai-tools:
    build:
      context: .
      dockerfile: Dockerfile
    image: ai-tools:latest
    container_name: ai-tools
    restart: unless-stopped
    tty: true
    stdin_open: true
    environment:
      - TZ=Europe/Bucharest      # Change to your timezone
    env_file:
      - .env                     # API keys - do not commit this file
    volumes:
      - ${HOME}/dev-home:/home/pn
      - ${HOME}/websites:/home/pn/app/websites
    security_opt:
      - no-new-privileges:true
    # Uncomment only if a tool needs an OAuth callback or a local server
    # ports:
    #   - "127.0.0.1:3000:3000"  # bind to localhost, not 0.0.0.0

services:
  ai-tools:
    build:
      context: .
      dockerfile: Containerfile
    image: ai-tools:latest
    container_name: ai-tools
    restart: unless-stopped
    tty: true
    stdin_open: true
    environment:
      - TZ=Europe/Bucharest      # Change to your timezone
    env_file:
      - .env                     # API keys - do not commit this file
    volumes:
      - ${HOME}/dev-home:/home/pn:z
      - ${HOME}/websites:/home/pn/app/websites:z
    security_opt:
      - no-new-privileges:true
    # Uncomment only if a tool needs an OAuth callback or a local server
    # ports:
    #   - "127.0.0.1:3000:3000"  # bind to localhost, not 0.0.0.0

Valida el archivo antes de compilar. Compose ignora silenciosamente las erratas en algunos campos:

docker compose config
# or: podman compose config

Si el YAML combinado se imprime y el servicio ai-tools tiene ambos volúmenes, todo bien. Si falta un volumen en la salida, tienes un problema de indentación.

Cuándo exponer puertos para callbacks de OAuth

La mayoría de las herramientas CLI de IA se autentican con una clave API en una variable de entorno o con un flujo de código de dispositivo (imprimen una URL, pegas un código). Ninguna de las dos necesita un puerto.

Añade un puerto solo cuando una herramienta abre un listener HTTP local para una redirección OAuth en localhost:

Vincula el puerto publicado a 127.0.0.1, no a todas las interfaces. "3000:3000" publica en todas las interfaces que tiene el host, que en un VPS significa internet. "127.0.0.1:3000:3000" no.

Paso 4: compila e inicia el contenedor

cd ~/docker-ai-tools

# Build the image
docker compose build

# Start the container detached
docker compose up -d

# Enter the container
docker exec -it ai-tools bash

docker compose down

cd ~/podman-ai-tools

# Ensure the Podman machine is running (macOS/Windows only)
podman machine start

# Build the image
podman compose build

# Start the container detached
podman compose up -d

# Enter the container
podman exec -it ai-tools bash

podman compose down

Verifica que realmente está en ejecución:

docker compose ps

NAME       IMAGE            COMMAND                  SERVICE   STATUS
ai-tools   ai-tools:latest  "/usr/local/bin/boot.…"  ai-tools  Up 12 seconds

Up es lo que quieres. Restarting en bucle significa que el entrypoint está fallando: consulta la solución de problemas.

La primera compilación tarda unos minutos (descarga una imagen base de ~580 MB). Las siguientes van por caché. Usa --no-cache solo cuando hayas cambiado de verdad la imagen base; tira todas las capas y vuelve a descargar todo.

Paso 5: verifica el entorno del contenedor

Dentro del contenedor, comprueba que las versiones son las que prometía la etiqueta:

# You should not be root
whoami
id -u
# Expected: pn
# Expected: 1000

# Node and package managers
node -v            # v26.8.2
npm -v             # 11.x
yarn -v            # 4.x (via Corepack)

# Python and package managers
python3 -V         # Python 3.14.7
pip --version      # 25.x
poetry --version
uv --version

# Shell tooling
which starship
# Expected: /usr/local/bin/starship

# Mounts
ls -la ~/app/websites
touch ~/app/websites/.mount-test && ls -la ~/app/websites/.mount-test

Ese touch es la prueba que importa. Si falla, el montaje está mal y solo te enterarías más tarde, cuando el agente escriba un archivo en un directorio local del contenedor que desaparece en el próximo docker compose down.

ls -la ~/websites/.mount-test

rm ~/websites/.mount-test

Paso 6: instala las herramientas CLI de IA (Claude Code, Amp, Gemini CLI, OpenCode)

¿No sabes qué agente elegir? Comparamos las mejores herramientas y agentes de programación con IA en 2026. Instala más de una: pesan 10-100 MB cada una y no hay ninguna desventaja en tener Claude Code, Amp y OpenCode lado a lado.

A partir de aquí, todo se ejecuta dentro del contenedor, así que los comandos son idénticos para Docker y Podman. Entra una vez:

docker exec -it ai-tools bash   # or: podman exec -it ai-tools bash

# Docker
docker exec -it --user root ai-tools bash
# Podman
podman exec -it --user root ai-tools bash

Instala Claude Code en el contenedor

El instalador nativo es el que debes usar. No le importa tu versión de Node y se actualiza solo.

# Native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash

# Verify
claude --version

Si la configuración de Node de tu imagen base choca con el binario nativo, la vía npm sigue funcionando:

npm install -g @anthropic-ai/claude-code
claude --version

Dónde acaban las cosas: el instalador nativo pone el binario en ~/.local/bin por defecto, así que sobrevive a una reconstrucción del contenedor solo porque ~/.local vive dentro del /home/pn montado por bind. Esa es la razón de que exista el montaje del home.

Instala Amp y Factory.ai

# Amp
curl -fsSL https://ampcode.com/install.sh | bash

# Factory.ai CLI
curl -fsSL https://app.factory.ai/cli | sh

# Verify
amp --version
droid --version

Amp retiró su plan gratuito durante 2025, así que revisa los precios actuales antes de construir un flujo de trabajo alrededor. Contexto sobre cómo funciona en el editor: Amp Code, agente de programación con IA.

La CLI Droid de Factory es la otra que vale la pena instalar aquí, sobre todo si quieres apuntarla a tus propios endpoints de modelos en lugar de una suscripción empaquetada:

Puedes configurar Factory para que use tus propios proveedores (incluido un Ollama local): el ejemplo de archivo de configuración está más abajo.

Instala Gemini CLI, OpenCode y GitHub Copilot CLI

# Gemini CLI
npm install -g @google/gemini-cli

# GitHub Copilot CLI (needs a Copilot subscription)
npm install -g @github/copilot

# OpenCode
curl -fsSL https://opencode.ai/install | bash

# Verify all three
gemini --version
copilot --version
opencode --version

Dos notas de la versión de 2025 de esta guía:

• GitHub Copilot CLI cambió de paquete. El antiguo paquete beta @githubnext/github-copilot-cli está muerto. El actual es @github/copilot. Si ves una advertencia de obsolescencia, estás en el paquete viejo.
• OpenCode se instala en ~/.opencode/bin en las versiones recientes, no en /usr/local/bin. Si te aparece opencode: command not found tras una instalación limpia, añade ~/.opencode/bin a tu PATH en el .bashrc sembrado.

¿Quieres saltarte la gestión de seis claves API? La suscripción OpenCode Go agrupa un montón de modelos detrás de una sola clave, que es la forma más barata de ejecutar un agente en contenedor sin una cartera llena de tokens:

Configuración completa, incluido el inicio de sesión en Zen y la configuración de proveedores: guía de configuración de OpenCode. Para los detalles de Copilot (modelos, límites del plan, el nivel de $10), consulta nuestra configuración de GitHub Copilot Pro CLI.

Y si prefieres enrutar Claude Code, Codex y Gemini CLI a través de un único endpoint con una clave y facturación por modelo, para eso sirve un agregador:

Autenticación con las herramientas CLI (OAuth y claves API)

# Device-code or browser flows
claude          # then /login inside the session
amp login
droid           # then /login inside the session
opencode auth login
copilot         # then /login
gemini          # follow the auth prompt

ports:
  - "127.0.0.1:3000:3000"

Trabajar con proyectos

~/websites en tu host es /home/pn/app/websites dentro del contenedor. Eso significa:

Flujo de trabajo de ejemplo: el host edita, el contenedor ejecuta

# On the host
cd ~/websites
mkdir my-new-project && cd my-new-project
git init

# Inside the container
cd ~/app/websites/my-new-project
amp "Create a Next.js app with TypeScript"

Una trampa: no ejecutes el mismo gestor de paquetes en ambos lados del montaje. Si el host ejecuta npm install y el contenedor ejecuta pnpm install en el mismo directorio, se pelean por node_modules. Elige un lado como autoridad: dentro del contenedor es la opción sensata, porque las versiones del runtime están fijadas ahí.

Configurar las herramientas de IA dentro del contenedor

Las configuraciones persisten porque ~/dev-home se asigna a /home/pn. Edítalas desde cualquiera de los dos lados; una sesión de nano dentro del contenedor y code ~/dev-home/... en el host tocan el mismo archivo.

Ejemplo: modelos personalizados en Factory.ai

# Inside the container
nano ~/.factory/config.json

{
  "custom_models": [
    {
      "model_display_name": "Claude Sonnet 4.5",
      "model": "claude-sonnet-4-5-20250929",
      "base_url": "https://api.anthropic.com",
      "api_key": "your-api-key-here",
      "provider": "anthropic",
      "max_tokens": 8192
    },
    {
      "model_display_name": "GPT-5 Codex",
      "model": "gpt-5-codex",
      "base_url": "https://api.openai.com/v1",
      "api_key": "your-openai-key-here",
      "provider": "openai",
      "max_tokens": 8192
    },
    {
      "model_display_name": "Qwen 3 (Local Ollama)",
      "model": "qwen3:14b",
      "base_url": "http://ollama:11434/v1",
      "api_key": "ollama",
      "provider": "generic-chat-completion-api",
      "max_tokens": 4096
    }
  ]
}

Fíjate en el base_url de Ollama: http://ollama:11434/v1, no http://localhost:11434/v1. Dentro de un contenedor, localhost es el propio contenedor. Si ejecutas Ollama como un servicio compose aparte (recomendado, ver abajo), el nombre del servicio es el hostname.

Acceder a los archivos del host desde el contenedor

# Inside the container
ls -la ~/.factory/     # Factory.ai configs
ls -la ~/.amp/         # Amp configs
ls -la ~/.config/      # everything else
cat ~/.bashrc          # shell config

Edita los mismos archivos desde el host:

# On the host
code ~/dev-home/.factory/config.json
code ~/dev-home/.bashrc
code ~/dev-home/.config/starship.toml

Los cambios tienen efecto en el siguiente shell dentro del contenedor (o al instante, para los archivos de configuración que las herramientas releen en cada petición).

sudo chown 1000:1000 ~/dev-home/.factory/config.json

Configuración avanzada

Ejecutar modelos de IA locales con Ollama

La versión de 2025 de esta guía te decía que instalaras Ollama dentro del contenedor del agente. No lo hagas. Infla la imagen del agente y los pesos de los modelos acaban en un volumen que se borra al reconstruir. Ejecuta Ollama como su propio servicio y deja que el agente le hable por la red de compose.

Añade un segundo servicio a tu archivo compose:

services:
  ai-tools:
    # ... your existing config ...
    environment:
      - TZ=Europe/Bucharest
      - OLLAMA_HOST=http://ollama:11434
    depends_on:
      - ollama

  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    volumes:
      - ${HOME}/ollama:/root/.ollama
    # Only publish this if you want to reach it from the host too.
    # Don't publish it on a VPS.
    # ports:
    #   - "127.0.0.1:11434:11434"

Luego descarga un modelo y apunta una herramienta a él:

docker compose up -d
docker exec -it ollama ollama pull qwen3:14b
docker exec -it ollama ollama list

# From inside ai-tools, confirm the name resolves
docker exec -it ai-tools curl -s http://ollama:11434/api/tags | jq '.models[].name'

    deploy:
      resources:
        limits:
          memory: 12g

Si quieres la pila completa de Ollama con una interfaz web, nuestra guía de autoalojar Ollama con Docker Compose cubre Open WebUI, la gestión de modelos y la configuración de GPU.

Configuraciones con varios contenedores

Contenedores separados por contexto evitan que las claves API y los contextos se mezclen:

~/docker-ai-tools-personal/
  ├── docker-compose.yml     # container_name: ai-tools-personal
  ├── Dockerfile
  └── .env                   # personal keys

~/docker-ai-tools-work/
  ├── docker-compose.yml     # container_name: ai-tools-work
  ├── Dockerfile
  └── .env                   # work keys, separate ~/websites mount

Cambia el container_name y las rutas de montaje en cada archivo. Dos contenedores con el mismo container_name se negarán a arrancar: Compose falla con un conflicto de nombres, que al menos es un fallo claro.

Compartir contenedores con el equipo

cd ~/docker-ai-tools
git init

Crea un .gitignore antes del primer commit:

cat > .gitignore <<'EOF'
.env
dev-home/
websites/
EOF

git add Dockerfile docker-compose.yml .gitignore
git commit -m "Add AI tools container config"

Un compañero ejecuta entonces:

git clone <your-repo>
cd <your-repo>
cp .env.example .env    # fill in their own keys
mkdir -p ~/dev-home ~/websites
docker compose up -d
docker exec -it ai-tools bash

El mismo Node, el mismo Python, las mismas herramientas instaladas. Esa es la parte de entorno de desarrollo reproducible de todo esto, y es la razón por la que hacer commit del Dockerfile vale esos cinco minutos.

Integración con el IDE

El contenedor es donde se ejecutan las herramientas. Tu editor se queda en el host, donde ya viven tu renderizado de fuentes, tus extensiones y tus atajos de teclado.

VS Code Dev Containers para agentes de IA

Dev Containers permite a VS Code ejecutar su servidor dentro del mismo contenedor que usa el agente, de modo que el terminal integrado, las tareas y el agente ven runtimes idénticos. Crea ~/docker-ai-tools/.devcontainer/devcontainer.json:

{
  "name": "ai-tools",
  "dockerComposeFile": ["../docker-compose.yml"],
  "service": "ai-tools",
  "workspaceFolder": "/home/pn/app/websites",
  "remoteUser": "pn",
  "shutdownAction": "stopCompose",
  "customizations": {
    "vscode": {
      "extensions": ["esbenp.prettier-vscode", "dbaeumer.vscode-eslint"]
    }
  }
}

Pasos:

1. Instala la extensión Dev Containers (el antiguo nombre “Remote - Containers” ya no existe).
2. Abre la carpeta ~/docker-ai-tools en VS Code.
3. Ejecuta Dev Containers: Reopen in Container.

Si VS Code se queja de que el contenedor ya existe, lo tienes en ejecución desde docker compose up -d. Ejecuta primero docker compose down: Dev Containers quiere ser dueño del ciclo de vida.

Para una alternativa basada en terminal en macOS orientada a flujos de trabajo con agentes, mira nuestra guía del terminal cmux para agentes de programación con IA. Y si prefieres tener la IA dentro del propio editor en lugar de en un shell de contenedor:

Edición directa de archivos desde el host

La opción más simple, y la que la mayoría de la gente acaba usando:

# On the host
code ~/websites/my-project

# In the container, the agent sees the changes immediately
cd ~/app/websites/my-project
amp "Refactor this component"

Los bind mounts no sincronizan: son el mismo inodo. No hay paso de “esperar a que sincronice” ni posibilidad de una copia desfasada en un lado.

Solución de problemas

# On the host
id -u
ls -lan ~/websites | head -3

# In the container
docker exec -it ai-tools id

sudo chown -R 1000:1000 ~/dev-home ~/websites

    user: "1002:1002"
    environment:
      - HOME=/home/pn

chcon -Rt container_file_t ~/dev-home ~/websites

docker compose logs --tail 50
docker logs ai-tools

podman compose logs --tail 50
podman logs ai-tools

droid
# then /login; if it prints a URL, paste that URL into your host browser

docker inspect ai-tools --format '{{json .Mounts}}' | jq
docker inspect ai-tools --format '{{.HostConfig.Privileged}}'

podman inspect ai-tools --format '{{json .Mounts}}' | jq

/home/you/dev-home  ->  /home/pn
/home/you/websites  ->  /home/pn/app/websites

Instalar comandos que faltan en el contenedor

Las imágenes base son mínimas a propósito. Te encontrarás con command not found la primera vez que un agente quiera rg, ffmpeg o un cliente de Postgres:

bash: rg: command not found
bash: psql: command not found

Dos formas de arreglarlo.

Opción 1: instalar temporalmente (solución rápida)

# Enter as root
docker exec -it --user root ai-tools bash

# Always update the index first, or apt can't find the package
apt-get update
apt-get install -y ripgrep postgresql-client

exit
docker exec -it ai-tools bash

# Enter as root
podman exec -it --user root ai-tools bash

apt-get update
apt-get install -y ripgrep postgresql-client

exit
podman exec -it ai-tools bash

Opción 2: actualiza el Dockerfile y reconstruye (permanente)

Añade el paquete a la línea apt-get install y reconstruye:

RUN apt-get update && apt-get install -y --no-install-recommends \
    git \
    jq \
    curl \
    vim \
    nano \
    htop \
    tree \
    ripgrep \
    rsync \
    postgresql-client \
    ffmpeg \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

Luego:

cd ~/docker-ai-tools
docker compose build
docker compose up -d
docker exec -it ai-tools bash

# Verify
rg --version
psql --version

cd ~/podman-ai-tools
podman compose build
podman compose up -d
podman exec -it ai-tools bash

# Verify
rg --version
psql --version

Paquetes comunes que podrías necesitar

Buenas prácticas de seguridad para agentes de IA en sandbox

Tu configuración de contenedor es un conjunto de capacidades. Todo lo de esta lista reduce lo que el agente puede hacer si algo sale mal.

Montajes de solo lectura y límites de recursos

Dos cambios de compose que recortan el radio de explosión sin romper nada:

services:
  ai-tools:
    # ... your existing config ...
    security_opt:
      - no-new-privileges:true   # blocks setuid escalation inside the container
    mem_limit: 8g                # kill the process instead of the host
    cpus: 4
    pids_limit: 512              # stops fork bombs from taking down the host

Verifica que los flags se aplicaron de verdad:

docker inspect ai-tools \
  --format 'mem={{.HostConfig.Memory}} pids={{.HostConfig.PidsLimit}} sec={{.HostConfig.SecurityOpt}}'

Esperado: mem=8589934592, pids=512 y [no-new-privileges:true]. Si mem=0, el límite no se aplicó y el agente puede consumir toda la RAM del host.

Ahora la versión más fuerte, para cuando el agente solo necesita leer un árbol de referencia:

    volumes:
      - ${HOME}/dev-home:/home/pn
      - ${HOME}/websites:/home/pn/app/websites
      - ${HOME}/reference-docs:/home/pn/reference:ro   # read-only

docker exec -it ai-tools sh -c 'touch /home/pn/reference/x' debería fallar con Read-only file system. Esa es la prueba.

Variables de entorno y claves API

Mantén las claves fuera de la imagen y fuera de git. Compose lee .env automáticamente para la sustitución de variables, y env_file inyecta los valores en el contenedor:

# docker-compose.yml or podman-compose.yml
services:
  ai-tools:
    env_file:
      - .env
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - GEMINI_API_KEY=${GEMINI_API_KEY}

# ~/.env - never commit this
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=...

La otra dirección también importa: no pases todo tu entorno del host al contenedor. env_file: .env con cinco claves nombradas es deliberado. docker run -e $(env) es entregarle al agente tu token de sesión de AWS.

Si quieres la mecánica de ARG vs ENV vs la sustitución de Compose, nuestra guía sobre usar ARG y ENV para variables de entorno en Docker Compose cubre las diferencias y el orden de precedencia.

Limpieza

Eliminar contenedor e imágenes

# Stop and remove the container
docker compose down

# Remove the built image
docker rmi ai-tools:latest

# Remove dangling images, stopped containers, and unused networks
docker system prune

# Also remove unused volumes - read the warning below first
docker system prune -a --volumes

podman compose down
podman rmi ai-tools:latest
podman system prune

Si el uso de disco de Docker sigue creciendo y prune no basta, el culpable suele ser el almacén de capas overlay2. Cubrimos recuperar espacio en disco de /var/lib/docker/overlay2 por separado.

Para una referencia rápida de los comandos que realmente escribirás, nuestra lista de comandos esenciales de Docker vale un marcador.

Empezar de cero

docker compose down
docker rmi ai-tools:latest

# Optional: reset configs and auth state
# This deletes every CLI config and login in the container home
rm -rf ~/dev-home/*

# Optional: reset the image cache entirely
docker builder prune -af

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

Ese rm -rf ~/dev-home/* es el único paso irreversible de toda esta guía. Borra tus tokens de autenticación y las configuraciones de las herramientas. ~/websites queda intacto.

Docker vs Podman para herramientas de IA

El resumen honesto: para este caso de uso la diferencia es menor de lo que sugiere internet. Ambos ejecutan este mismo archivo compose, ambos soportan la misma imagen y ambos te dan el aislamiento que buscas.

Elige Docker si: tu equipo ya lo usa, quieres el mayor ecosistema de ejemplos e integraciones de CI, o estás en macOS y quieres la experiencia de escritorio más suave.

Elige Podman si: estás en Fedora/RHEL, quieres contenedores rootless sin configuración extra, o te importa que no haya un daemon root siempre activo al que atacar.

Para un contenedor que ejecuta un agente con acceso a shell, el argumento de “sin proceso root persistente y sin socket de Docker” es el que realmente importa para la seguridad. El mecanismo es simple: si el agente encuentra /var/run/docker.sock dentro de su contenedor, puede levantar un contenedor privilegiado y ser root en tu host en unos tres comandos.

El desglose completo de arquitectura, licencias y rutas de migración está en nuestro artículo Podman vs Docker comparados.

Ejemplos de uso reales

Ejemplo 1: Factory.ai con modelos personalizados

# Inside the container
cd ~/app/websites/my-app

droid

# In the Droid prompt, pick your model
/model
# Choose "Claude Sonnet 4.5" from custom models

"Add user authentication with Supabase, including sign-up, login, and protected routes"

El valor de la configuración de modelos personalizados: puedes apuntar Factory a un agregador barato para las ediciones rutinarias y a un modelo de frontera solo cuando lo necesitas, sin cambiar nada en el host.

Ejemplo 2: Amp con contexto de proyecto

cd ~/app/websites/nextjs-blog

cat > AGENTS.md <<'EOF'
# Project: Next.js Blog

## Tech stack
- Next.js 15
- TypeScript
- Tailwind CSS
- MDX for blog posts

## Architecture
- App Router
- Server Components by default
- Client Components only when needed

## Commands
- Dev: npm run dev
- Build: npm run build
- Test: npm test
EOF

amp "Add a comments section using Supabase"

AGENTS.md es la ganancia de contexto más barata que existe. Es un archivo del proyecto, así que funciona para todos los agentes que lo lean, y funciona idéntico dentro del contenedor.

Ejemplo 3: varias herramientas de IA en secuencia

# One agent implements
amp "Create a React component for a product card"

# Another reviews
claude "Review the ProductCard component and suggest performance improvements"

# A third writes tests
droid "Generate unit tests for ProductCard.tsx"

Distintos modelos son buenos en cosas distintas, y ejecutarlos contra el mismo checkout significa que cada uno ve el trabajo del anterior. También es una forma barata de contrastar la salida de un agente con una segunda opinión.

Si quieres el siguiente paso —dejar que un asistente dirija despliegues de Docker en un servidor— eso es un problema distinto con un radio de explosión mayor, y escribimos sobre dejar que un asistente de IA despliegue apps Docker por separado.

Buenas prácticas para herramientas CLI de IA en contenedores

Preguntas frecuentes

# Terminal 1
docker exec -it ai-tools bash
cd ~/app/websites/project1
amp "Implement feature X"

# Terminal 2, same container
docker exec -it ai-tools bash
cd ~/app/websites/project2
claude "Review the auth code"

# Inside the container
claude update
amp update
droid update

# npm-installed tools
npm update -g @google/gemini-cli
npm update -g @github/copilot

# .github/workflows/ai-review.yml
name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build AI tools image
        run: docker compose build
      - name: Run AI review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          docker compose up -d
          docker exec ai-tools claude -p "Review this PR for code quality and list any bug risks"

# Python 3.14 with Node 26 (what this guide uses)
FROM nikolaik/python-nodejs:python3.14-nodejs26-bookworm

# Python 3.13 with Node 26
FROM nikolaik/python-nodejs:python3.13-nodejs26-bookworm

# Slim variant - smaller, no build toolchain
FROM nikolaik/python-nodejs:python3.14-nodejs26-slim

Conclusión

Poner las herramientas CLI de IA en contenedores te da un sandbox en el que puedes permitirte ser descuidado. No una frontera de seguridad contra un atacante decidido, sino una frontera contra el modo de fallo que realmente ocurre: un agente que ejecuta un comando que no debería.

Con lo que acabas:

Las tres cosas que vale la pena hacer diferente respecto a la versión de 2025 de esta guía: pasar a python3.14-nodejs26-bookworm como imagen base, dejar de instalar Ollama dentro del contenedor del agente, y no montar por bind nada que no le entregarías en un prompt de shell.

Si estás construyendo el resto de la pila, las continuaciones que más importan son Podman vs Docker comparados si aún eliges motor, la guía de configuración de OpenCode o Amp Code, agente de programación con IA para la parte de herramientas, y las mejores herramientas y agentes de programación con IA en 2026 si prefieres comparar antes de comprometerte.