Docker y OrbStack

Instala el entorno de ejecución

Instala OrbStack —recomendado en una Mac— o Docker Desktop, y confirma que el demonio está corriendo.

brew install orbstack          # recommended — or install Docker Desktop
docker --version && docker info

El agente corre por completo dentro del contenedor, así que la única otra herramienta que necesitas en la Mac es Claude Code, usada una vez para generar el token del agente. Sáltala si ya la tienes.

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

Obtén la imagen

Descarga la imagen publicada y etiquétala como local/fragua:latest para que la guía y el archivo Compose coincidan. Descargarla evita la construcción de 10 a 15 minutos y te da la imagen publicada exacta.

docker pull ghcr.io/maquina-app/fragua-docker:latest
docker tag ghcr.io/maquina-app/fragua-docker:latest local/fragua:latest
docker image ls | grep fragua

ruby --version && node --version && rails --version
sqlite3 --version && pg_config --version && mysql_config --version
ffmpeg -version | head -1 && wkhtmltopdf --version
gh --version && claude --version && fragua --version

Crea los volúmenes e inicia sesión una vez

Todo lo que el agente necesita vive en cuatro volúmenes con nombre, así que el agente en marcha no depende de nada de tu Mac. Los configuras una vez; sobreviven cada reconstrucción.

Crea los cuatro volúmenes

docker volume create fragua-config
docker volume create fragua-secrets
docker volume create fragua-workdir
docker volume create fragua-data
docker volume ls | grep fragua

Genera el token de Claude (en tu Mac)

El inicio de sesión interactivo de Claude Code necesita un navegador, que un contenedor sin pantalla no puede abrir. Genera un token de larga duración en la Mac: lo pegas en un volumen enseguida, y el contenedor lo lee de ahí en cada corrida.

claude setup-token

Abre la sesión de configuración única

Abre una shell de una sola vez con los volúmenes de configuración y de secretos montados con escritura. Es la única vez que el volumen de secretos tiene escritura: al correr baja a solo lectura, así que el agente usa el token de GitHub y la llave SSH pero nunca los reescribe.

docker run --rm -it \\
  -v fragua-config:/fragua-config:rw \\
  -v fragua-secrets:/fragua-secrets:rw \\
  local/fragua:latest bash

Dentro del contenedor, crea los directorios de secretos y luego inicia sesión en GitHub. El flujo de código de dispositivo funciona sin pantalla: imprime un código y una URL. La bandera --insecure-storage escribe el token en el volumen de secretos para que persista; sin ella gh puede guardarlo en un llavero dentro de la VM que desaparece en la siguiente corrida.

mkdir -p /fragua-secrets/gh /fragua-secrets/ssh && chmod 700 /fragua-secrets/ssh
gh auth login --insecure-storage

Dale al contenedor su propia llave SSH en vez de copiar la tuya personal. Una llave dedicada está aislada de tu Mac y puedes revocarla por separado. Define una identidad de Git, genera la llave y regístrala en GitHub:

git config --global user.name  "Your Name"
git config --global user.email "[email protected]"

chmod 700 /root/.ssh
ssh-keygen -t ed25519 -f /root/.ssh/id_ed25519 -N "" -C "fragua-docker"
gh auth refresh -h github.com -s admin:public_key
gh ssh-key add /root/.ssh/id_ed25519.pub --title "fragua-docker"
ssh -o IdentitiesOnly=yes -i /root/.ssh/id_ed25519 -T [email protected]

¿Usas remotos https:// en vez de [email protected]? Sáltate la llave por completo y corre gh auth setup-git para que gh actúe como ayudante de credenciales de git.

Avanzado: puedes reutilizar una llave del host montándola y copiándola una vez, pero solo si no tiene frase de paso; bajo tu propio riesgo.

Pega el token de claude setup-token en el volumen de configuración. El entrypoint de la imagen lee este archivo en cada corrida, así que no lo vuelves a pasar.

printf '%s' 'PASTE_THE_setup-token_VALUE' > /fragua-config/claude-oauth-token
chmod 600 /fragua-config/claude-oauth-token
claude -p "reply with the single word: ok"

Por último, conecta la CLI de Fragua con el AgentToken de tu página de Configuración, revisa la instalación y sal de la shell.

fragua login
fragua doctor
exit

Corre el agente

Un compose.yaml monta solo los cuatro volúmenes, sin rutas del host. Tómalo aquí abajo, levántalo, sigue los logs y revisa el estado del agente.

services:
  fragua-agent:
    image: local/fragua:latest
    volumes:
      - fragua-config:/fragua-config:rw     # fragua status/DB, git identity, claude token + state
      - fragua-secrets:/fragua-secrets:ro   # gh token + SSH key (read-only at runtime)
      - fragua-workdir:/fragua-workdir:rw   # agent working tree
      - fragua-data:/fragua-data:rw         # claude + fragua CLIs, runtime gems + node modules
    restart: unless-stopped

volumes:
  fragua-config:
    external: true
  fragua-secrets:
    external: true
  fragua-workdir:
    external: true
  fragua-data:
    external: true

docker compose up -d
docker compose logs --follow
docker compose exec fragua-agent fragua status

¿Prefieres un docker run de una sola vez? Aquí está el equivalente del archivo Compose:

docker run -d --name fragua-agent --restart unless-stopped \\
  -v fragua-config:/fragua-config:rw \\
  -v fragua-secrets:/fragua-secrets:ro \\
  -v fragua-workdir:/fragua-workdir:rw \\
  -v fragua-data:/fragua-data:rw \\
  local/fragua:latest

Día a día

Recónstruye o actualiza el agente. Cada volumen sobrevive a docker compose down y a las reconstrucciones de imagen, así que no hay que volver a configurar.

# rebuild — every volume survives, no re-setup
docker compose exec fragua-agent fragua prune --yes
docker compose down
docker build --no-cache -t local/fragua:latest .
docker compose up -d --force-recreate   # recreate so the new image's CLIs are adopted (plain up -d/start keeps the old container)

# update the CLIs (Claude Code + fragua) a running agent uses — no rebuild
docker compose exec fragua-agent fragua-refresh-cli   # both (or: claude / fragua)
# (refresh only the image's offline baseline instead: ./build.sh --refresh-cli)

# inspect the workdir without touching the running agent
docker run --rm -v fragua-workdir:/data:ro alpine ls -la /data

# drop the runtime gem/node cache + CLIs (re-bootstrapped on next start, keeps creds)
docker volume rm fragua-data && docker volume create fragua-data

Solución de problemas

claude /login falla con "Invalid OAuth Request / Unknown scope"

El redirect del navegador no puede completarse en un contenedor sin pantalla. Corre claude setup-token en tu Mac y escribe el resultado en /fragua-config/claude-oauth-token.

git push falla con "Permission denied (publickey)"

La llave del contenedor no está en GitHub. Vuelve a correr gh ssh-key add /root/.ssh/id_ed25519.pub en la shell de configuración y prueba con ssh -T [email protected].

gh dice "not logged in" cuando el agente ya corre

El volumen fragua-secrets no está montado o está vacío. Vuelve a correr gh auth login --insecure-storage en la shell de configuración y confirma que el volumen esté listado en tu compose.yaml.

git por HTTPS falla con "could not read Username for https://github.com"

No hay un ayudante de credenciales de git conectado al token de gh: el agente se configuró solo con SSH. Corre gh auth setup-git una vez en la shell de configuración; escribe el ayudante en /fragua-config/gitconfig y persiste.

claude rechaza --dangerously-skip-permissions con "cannot be used with root/sudo privileges"

La imagen corre como root por diseño y define IS_SANDBOX=1 para que Claude Code reconozca el contenedor aislado. Si te topas con esto, estás en una imagen vieja construida antes de esa variable: reconstruye, o define IS_SANDBOX=1 al invocar claude.

Un host x86 no puede correr una imagen arm64

Publica una imagen multiarquitectura con ./build.sh --platform linux/amd64,linux/arm64 para que hosts Intel y ARM puedan descargar la misma etiqueta.