Agente en contenedor aislado

Apple Container

Corre el agente en una VM de macOS totalmente aislada: base completa de Rails, nada expuesto a tu Mac.

Apple Container corre cada agente en su propia VM ligera con una base completa de Rails y cada librería nativa preinstalada. El trabajo del agente —clones, bundle install, migraciones, compilación de assets— se queda dentro de sus volúmenes, y nada en la carpeta personal de tu Mac queda expuesto.

¿Cuál entorno?

Apple Container

Estás aquí

El mayor aislamiento: cada agente corre en su propia VM ligera. La opción nativa y delgada en una Mac reciente.

Apple silicon · macOS 15+

Docker y OrbStack

Corre donde corra Docker, Intel o ARM, con un archivo Compose listo. OrbStack lo mantiene ligero en una Mac.

Docker u OrbStack · Intel o Apple silicon

¿No es lo que buscas? Configura Docker y OrbStack en su lugar.

Requiere Apple silicon (serie M) y macOS 15 o posterior.

Instala el entorno de ejecución

Instala la CLI de Apple Container desde su página de versiones —un .pkg que abres con doble clic— y luego inicia el entorno. El primer arranque instala un kernel de VM de Linux; responde Y cuando lo pida.

open https://github.com/apple/container/releases/latest
container --version
container system start
container system status

Si container system start se atora en "Verifying machine API server", el kernel aún no está instalado. Corre container system kernel set --recommended y arranca de nuevo.

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 el resto de los comandos de la guía coincidan. Descargarla evita la construcción de 10 a 15 minutos y te da la imagen publicada exacta.

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

Qué trae la imagen

La imagen es un entorno Rails completo construido sobre Ubuntu 24.04. No tienes que confiar a ciegas: esto es lo que trae, y un comando para confirmarlo tú mismo.

Entornos de lenguajes: Ruby y Node, gestionados por mise. El .mise.toml propio de un proyecto sobrescribe las versiones globales automáticamente.
Cadena de herramientas de Ruby: Bundler y Rails preinstalados, con banderas de compilación conectadas a las librerías del sistema para que gemas nativas como nokogiri, pg, mysql2 y hiredis compilen sin líos.
Librerías nativas: Toda la base que necesita bundle install: herramientas de compilación, SSL y cripto, SQLite, PostgreSQL y MySQL, imagen y multimedia (ImageMagick, libvips, WebP, ffmpeg), PDF (wkhtmltopdf y tipografías), libxml, Protobuf y gRPC, geoespacial (GEOS, PROJ), y renderizado con Pango/Cairo.
Herramientas de línea de comandos: GitHub CLI, git, Claude Code y la CLI de Fragua: todo lo que el agente necesita para clonar, construir y subir cambios.

Confirma la base desde dentro del contenedor:

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

Corre esto en la sesión de configuración de abajo, o en cualquier shell del contenedor. Cada línea debe imprimir una versión.

¿Quieres cambiar lo que se instala: agregar una librería, fijar una versión, construir multiarquitectura? El Dockerfile y el script de construcción viven en el repo de fragua-tools, con notas para personalizar y publicar tu propia imagen.

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

container volume create fragua-config
container volume create fragua-secrets
container volume create fragua-workdir
container volume create fragua-data
container volume list

fragua-config

/fragua-config

Token de Fragua y estado local, tu identidad de Git, el token de Claude y el estado de sesión y por proyecto de Claude Code.

fragua-secrets

/fragua-secrets

El token de GitHub CLI y la llave SSH propia del contenedor, juntos. Solo lectura cuando el agente está corriendo, así que los usa pero nunca los reescribe.

fragua-workdir

/fragua-workdir

El árbol de trabajo del agente: clones, bundle install, bases de datos, assets compilados.

fragua-data

/fragua-data

Los CLIs de Claude Code y fragua, además de las gemas y paquetes de Node que el agente instala al correr — guardados para que una reconstrucción no los descargue de nuevo.

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.

container 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-container"
gh auth refresh -h github.com -s admin:public_key
gh ssh-key add /root/.ssh/id_ed25519.pub --title "fragua-container"
ssh -o IdentitiesOnly=yes -i /root/.ssh/id_ed25519 -T [email protected]

Qué significa una llave generada para tu seguridad

Una llave dedicada al contenedor es la opción más segura, pero conoce las concesiones:

La llave privada no tiene frase de paso —un agente sin pantalla no puede escribirla—, así que queda sin cifrar en el volumen fragua-secrets. Quien pueda leer ese volumen puede leer la llave, pero es una llave de un solo uso, no la tuya personal.
Registrarla con gh ssh-key add otorga acceso de escritura a tu cuenta de GitHub. Trátala como una credencial viva y dale un título claro, para que la encuentres y la revoques después con gh ssh-key delete o en GitHub → Configuración → Llaves SSH.
Los commits se atribuyen al nombre y correo que defines aquí, no a tu identidad de siempre: ponlos a propósito para que los commits del agente se reconozcan.
gh auth refresh -s admin:public_key amplía el alcance del token de gh para que pueda agregar la llave. Ese token vive en fragua-secrets y se monta como solo lectura cuando el agente corre.
Aun así es la postura más segura: la llave es dedicada, revocable y nunca toca ~/.ssh. Reutilizar tu llave del host la copiaría al volumen, y una llave con frase de paso tendría que quedar sin ella para funcionar sin pantalla, dejando una copia sin cifrar de tu llave real.

¿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

El agente monta solo estos volúmenes con nombre: sin rutas del host. Los volúmenes de configuración y trabajo quedan con escritura; el token de GitHub y la llave SSH bajan a solo lectura para que el agente los use pero nunca los reescriba.

fragua-config rw

/fragua-config

fragua-secrets ro

/fragua-secrets

fragua-workdir rw

/fragua-workdir

fragua-data rw

/fragua-data

container run \\
  --name fragua-agent \\
  --detach \\
  -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

La máquina aparece en línea en segundos: obsérvala en tu página de Agentes. El .mise.toml propio de un proyecto fija sus versiones de Ruby y Node automáticamente.

Día a día

Observa el agente, recónstrúyelo o bórralo. Cada volumen sobrevive una reconstrucción, así que no hay que volver a iniciar sesión ni se pierde trabajo.

container logs --follow fragua-agent
container exec -it fragua-agent bash

# rebuild — every volume survives, no re-login
container exec fragua-agent fragua prune --yes
container stop fragua-agent && container rm fragua-agent
container build --no-cache -t local/fragua:latest .

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

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

Solución de problemas

container system start se atora en "Verifying machine API server": El kernel de la VM no está instalado. Corre container system kernel set --recommended y luego container system start otra vez.
claude /login falla con "Invalid OAuth Request / Unknown scope": El redirect del navegador no puede completarse en un contenedor sin pantalla. No uses /login: 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].
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 la imagen: Las imágenes construidas en Apple silicon son arm64, y Apple Container es solo arm64. Para hosts Intel, construye y publica una imagen compatible con la construcción multiarquitectura de la guía de Docker.