🌍 English | Español | Français | Italiano | Português | Deutsch | Русский | हिन्दी | 中文 | 日本語 | 한국어

HolyCode

Un contenedor. Todas las herramientas. Cualquier proveedor.

OpenCode ejecutándose en un contenedor con todo ya instalado. Más de 50 herramientas de desarrollo, más de 10 proveedores de IA, navegador sin cabeza, estado persistente. Ponlo en cualquier máquina y continúa exactamente donde lo dejaste.

Funciona con tu suscripción de Claude. Activa el plugin Claude Auth y usa tu plan Claude Max/Pro existente. No necesitas una clave API separada.

Gestiona tu plugin multiagente por ahora. La instalación de oh-my-openagent administrada por HolyCode queda suspendida en v1.1.4. El primer arranque correcto sin el ajuste antiguo desactiva la entrada administrada anterior y conserva los ajustes, las Skills y la caché del paquete.

Ibas a pasar una hora recuperando tu entorno. O simplemente puedes ejecutar docker compose up.

¿No quieres hacer el alojamiento propio? HolyCode Cloud está llegando. Las mismas herramientas, sin configuración. El acceso anticipado es gratuito.

¿Qué es esto?

Ya conoces la historia. Configuras tu entorno de desarrollo perfectamente. Luego cambias de máquina. O reconstruyes un contenedor. O tu sistema decide que hoy es el día en que muere.

De repente estás reinstalando herramientas. Buscando archivos de configuración. Reingresando claves API. Preguntándote por qué ripgrep ya no está en el PATH. Averiguando por qué Chromium no arranca porque Docker le da a los contenedores 64 MB de memoria compartida. Luego Xvfb no está configurado. Luego el UID dentro del contenedor no coincide con el del host y todo da permiso denegado.

HolyCode es el contenedor que construí después de resolver cada uno de esos problemas.

Envuelve OpenCode, un agente de programación con IA con una interfaz web integrada. Todos tus ajustes, sesiones, configuraciones MCP, plugins e historial de herramientas viven en un bind mount fuera del contenedor. Reconstruye, actualiza o muévete a una nueva máquina. Tu estado vuelve enseguida.

Es la misma idea que HolyClaude pero envolviendo OpenCode en lugar de Claude Code. Y esto es lo importante: OpenCode no está atado a un solo proveedor. Apúntalo a Anthropic, OpenAI, Google Gemini, Groq, AWS Bedrock o Azure OpenAI. El mismo contenedor, tu elección de modelo.

Más de 30 herramientas de desarrollo, dos entornos de ejecución de lenguajes, una pila de navegador sin cabeza y supervisión de procesos. Todo conectado, todo listo desde el primer arranque. He estado ejecutando esto en mi propio servidor. Cada error ha sido encontrado, diagnosticado y corregido.

Lo bajas. Lo ejecutas. Abres el navegador. Construyes.

Tabla de contenidos

🚀 Inicio rápido

Paso 1. Descarga la imagen.

docker pull coderluii/holycode:latest

Paso 2. Crea un docker-compose.yaml.

La configuración de Compose usa el perfil seccomp de Chromium de HolyCode. Si no ejecutas desde un clon del repositorio, descarga primero la copia de la versión:

mkdir -p config
curl -fsSLo config/chromium-seccomp.json \
  https://raw.githubusercontent.com/CoderLuii/HolyCode/v1.1.3/config/chromium-seccomp.json

services:
  holycode:
    image: coderluii/holycode:latest
    container_name: holycode
    restart: unless-stopped
    shm_size: 2g
    security_opt:
      - seccomp=./config/chromium-seccomp.json
    ports:
      - "4096:4096"
    volumes:
      - ./data/opencode:/home/opencode
      - ./local-cache/opencode:/home/opencode/.cache/opencode
      - ./workspace:/workspace
    environment:
      - PUID=1000
      - PGID=1000
      - ANTHROPIC_API_KEY=your-key-here

Paso 3. Inícialo.

docker compose up -d

Abre http://localhost:4096. Ya estás dentro.

El docker-compose.yaml incluido usa la sintaxis ${ANTHROPIC_API_KEY} que lee desde tu entorno de shell o un archivo .env. Copia .env.example a .env y rellena tu clave API.

volver arriba

☁ HolyCode Cloud (Próximamente)

¿No quieres hacer el alojamiento propio? Estamos construyendo una versión gestionada de HolyCode.

Las mismas 50+ herramientas. Los mismos 10+ proveedores. El mismo estado persistente. Sin Docker. Sin terminal. Solo abre tu navegador y programa.

Lo que obtienes con Cloud:

• Configuración cero. Sin Docker, sin archivos de configuración, sin comandos de terminal.
• Funciona en cualquier dispositivo. Portátil, tablet, teléfono. Abre un navegador y listo.
• Las versiones etiquetadas actualizan OpenCode y los pines de herramientas por ti.
• Tu estado te sigue. Sesiones, ajustes, configuraciones MCP guardadas entre usos.

El acceso anticipado es gratuito. No se requiere tarjeta de crédito.

Reserva tu lugar

volver arriba

💻 Plataformas compatibles

volver arriba

⚡ Por qué HolyCode

Lo construí porque estaba cansado de repetir la misma configuración cada vez. Instalar OpenCode, conectar un navegador sin cabeza, corregir problemas de permisos, depurar la supervisión de procesos. Cada. Vez.

Así que hice un contenedor que hace todo eso. Y luego encontré cada posible error para que tú no tengas que hacerlo.

volver arriba

🤖 Proveedores compatibles

OpenCode es agnóstico al proveedor. Configura la clave API que uses y listo.

Solo necesitas configurar claves para los proveedores que realmente uses. Todo lo demás es opcional y se ignora.

Vertex AI, GitHub Models y Ollama se configuran a través del sistema de proveedores de OpenCode. Ejecuta opencode providers login dentro del contenedor.

volver arriba

📋 Docker Compose - Rápido

La configuración mínima. Copia, rellena tu clave, ejecuta.

services:
  holycode:
    image: coderluii/holycode:latest
    container_name: holycode
    restart: unless-stopped
    shm_size: 2g              # Necesario para la estabilidad de Chromium
    ports:
      - "4096:4096"           # Interfaz web de OpenCode
    volumes:
      - ./data/opencode:/home/opencode
      - ./local-cache/opencode:/home/opencode/.cache/opencode
      - ./workspace:/workspace  # Los archivos de tu proyecto
    environment:
      - PUID=1000
      - PGID=1000
      - ANTHROPIC_API_KEY=your-key-here  # O cambia por cualquier clave de proveedor

volver arriba

📄 Docker Compose - Completo

Cada opción documentada. Copia en docker-compose.yaml y descomenta lo que necesites.

# HolyCode - Full Configuration Reference
# Copy this file to docker-compose.yaml and customize.
# All options documented. Uncomment what you need.

services:
  holycode:
    image: coderluii/holycode:latest
    container_name: holycode
    restart: unless-stopped
    shm_size: 2g

    ports:
      - "4096:4096"   # OpenCode web UI

    volumes:
      # --- Persistent state (all OpenCode data under home dir) ---
      - ./data/opencode:/home/opencode   # Config, sessions, plugins, all XDG paths

      # --- Cache isolation (keeps plugin cache on local disk, avoids CIFS/SMB symlink issues) ---
      - ./local-cache/opencode:/home/opencode/.cache/opencode

      # --- Workspace ---
      - ./workspace:/workspace   # Your project files

    environment:
      # --- Container user ---
      - PUID=1000                # Match your host UID for file permissions
      - PGID=1000                # Match your host GID for file permissions

      # --- Git identity (used on first boot) ---
      # - GIT_USER_NAME=Your Name
      # - [email protected]

      # --- AI provider API keys (add the ones you use) ---
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
      # - OPENAI_API_KEY=${OPENAI_API_KEY:-}
      # - GEMINI_API_KEY=${GEMINI_API_KEY:-}
      # - GROQ_API_KEY=${GROQ_API_KEY:-}
      # - GITHUB_TOKEN=${GITHUB_TOKEN:-}

      # --- AWS Bedrock (uncomment all 3 for Bedrock) ---
      # - AWS_ACCESS_KEY_ID=
      # - AWS_SECRET_ACCESS_KEY=
      # - AWS_REGION=us-east-1

      # --- Azure OpenAI (uncomment all 3 for Azure) ---
      # - AZURE_OPENAI_ENDPOINT=
      # - AZURE_OPENAI_API_KEY=
      # - AZURE_OPENAI_API_VERSION=

      # --- OpenCode behavior (set by default in image, override if needed) ---
      # - OPENCODE_DISABLE_AUTOUPDATE=true
      # - OPENCODE_DISABLE_TERMINAL_TITLE=true
      # - OPENCODE_MODEL=claude-sonnet-4-6
      # - OPENCODE_PERMISSION=auto
      # - OPENCODE_DISABLE_LSP_DOWNLOAD=true
      # - OPENCODE_DISABLE_AUTOCOMPACT=true
      # - OPENCODE_ENABLE_EXA=true

      # --- Web UI Security (basic auth for opencode web) ---
      # - OPENCODE_SERVER_PASSWORD=your-password
      # - OPENCODE_SERVER_USERNAME=opencode

      # --- Claude Auth (use Claude subscription instead of API key) ---
      # Reads credentials from ./data/opencode/.claude/.credentials.json
      # NOTE: May violate Anthropic TOS. Use at your own risk.
      # Toggle on/off with docker compose down && up -d
      # - ENABLE_CLAUDE_AUTH=true

      # --- Legacy oh-my-openagent flag ---
      # Managed installation is unavailable in v1.1.4. Existing config is preserved.
      # Startup stops with a migration message while this flag is true.
      # - ENABLE_OH_MY_OPENAGENT=true

volver arriba

🔧 Variables de entorno

ENABLE_CLAUDE_AUTH tiene efecto al reiniciar el contenedor. ENABLE_OH_MY_OPENAGENT ahora es un ajuste heredado y actualmente detiene el arranque con un aviso de migración.

HOLYCODE_PLUGIN_UPDATE controla las actualizaciones de los paquetes de plugins. manual (por defecto) instala los plugins habilitados solo si faltan y conserva las versiones instaladas por el usuario. auto instala los plugins faltantes y sincroniza los pins declarados al arrancar. Esto es independiente de OPENCODE_DISABLE_AUTOUPDATE, que solo afecta a OpenCode.

HolyCode no instala oh-my-openagent actualmente. Si una instalación anterior conserva ENABLE_OH_MY_OPENAGENT=true, el contenedor se detiene sin cambiar el estado del plugin. Después de quitar el ajuste, el primer arranque correcto desactiva la entrada activa anterior y conserva los ajustes, las Skills y la caché del paquete.

ENABLE_PAPERCLIP=true inicia Paperclip en el puerto 3100 dentro del contenedor. Abre el panel de control, crea una empresa y contrata agentes respaldados por OpenCode desde allí. Paperclip persiste en ~/.paperclip automáticamente.

Hermes sigue sin estar incluido en la imagen actual. Si una instalación anterior conserva ENABLE_HERMES=true, HolyCode detiene el arranque con un aviso breve de migración. /home/opencode/.hermes se conserva sin cambios para una futura restauración de la integración o para volver a una instantánea anterior.

GIT_USER_NAME y GIT_USER_EMAIL solo se aplican en el primer arranque. Para volver a aplicarlos, elimina el archivo centinela y reinicia: docker exec holycode rm /home/opencode/.config/opencode/.holycode-bootstrapped y luego docker compose restart.

volver arriba

📦 Qué hay dentro

volver arriba

🧩 Servicios incluidos

Paperclip sigue incluido como servicio opcional sobre OpenCode. La integración CLIProxyAPI continúa usando un endpoint administrado externamente. Hermes no está temporalmente en la imagen.

Hermes Agent (no incluido temporalmente)

Hermes sigue sin estar incluido. HolyCode no inicia ningún proceso de Hermes ni publica su puerto.

Los datos existentes en /home/opencode/.hermes no se eliminan ni se migran. Quita ENABLE_HERMES=true de configuraciones anteriores para iniciar la imagen actual. Conserva ese directorio para una futura restauración de la integración o para restaurar una instantánea anterior sin modificar.

Paperclip

Paperclip es la opción de "tablero de agentes". Te da un panel de control local en el puerto 3100 donde creas una empresa, contratas agentes y dejas que esos agentes se activen según un horario. Internamente lanza procesos opencode run, así que los trabajadores siguen siendo HolyCode.

Actívalo con:

environment:
  - ENABLE_PAPERCLIP=true
  - PAPERCLIP_PORT=3100

El estado de Paperclip vive en /home/opencode/.paperclip. Paperclip también se ejecuta con /home/opencode como home y mantiene la configuración, caché y estado de OpenCode bajo ese mismo directorio, así que los agentes ven la misma configuración persistente que la UI web de OpenCode. Paperclip ahora publica el catálogo de Skills mediante el conjunto de paquetes que instala HolyCode, así que la página Skills puede cargar el catálogo en vez de fallar con GET /api/skills/catalog. Abre el panel de control, configura tu empresa y contrata empleados respaldados por OpenCode desde allí.

volver arriba

🏗 Arquitectura

graph TD
    A[docker compose up -d] --> B[entrypoint.sh]
    B --> C[UID/GID Remap]
    C --> D[Plugin Toggles]
    D --> E{First Boot?}
    E -->|Yes| F[bootstrap.sh]
    E -->|No| G[s6-overlay /init]
    F --> G
    G --> H[Xvfb :99]
    G --> I[opencode web :4096]
    I --> J[Web UI]
    J --> K[Your Browser]
    I --> L[CLI Access]
    L --> M[docker exec -it holycode bash]
    M --> N[opencode TUI]
    M --> O[opencode run 'message']
    M --> P[opencode attach localhost:4096]

El punto de entrada gestiona la reasignación de usuario, los toggles de plugins, los toggles de servicios incluidos opcionales y la configuración del primer arranque. s6-overlay supervisa Xvfb, el servidor web de OpenCode y cualquier servicio incluido opcional que hayas habilitado. Si un proceso supervisado falla, s6 lo reinicia automáticamente. Accede a la interfaz web en el puerto 4096 o ejecuta dentro del contenedor para la experiencia completa de CLI.

volver arriba

💻 Uso de CLI

La interfaz web en el puerto 4096 es la interfaz principal. Pero también puedes usar OpenCode directamente desde la línea de comandos dentro del contenedor.

TUI interactivo

docker exec -it holycode bash
opencode

Esto abre la interfaz de terminal completa de OpenCode con todas las mismas funciones que la versión web.

Comandos puntuales

Ejecuta un solo prompt sin entrar en el TUI:

docker exec -it holycode bash -c "opencode run 'explain this codebase'"

Conectarse al servidor en ejecución

Conecta una sesión TUI local al servidor web de OpenCode ya en ejecución:

docker exec -it holycode bash -c "opencode attach http://localhost:4096"

Esto comparte la misma sesión que la interfaz web. Los cambios en uno aparecen en el otro.

Gestión de proveedores

Lista y configura proveedores de IA desde dentro del contenedor:

docker exec -it holycode bash -c "opencode providers list"
docker exec -it holycode bash -c "opencode providers login"

Migración de oh-my-openagent

HolyCode no instala ni actualiza oh-my-openagent en v1.1.4. Con ENABLE_OH_MY_OPENAGENT=true, el arranque se detiene sin cambiar el estado del plugin. Al quitar el ajuste, el primer arranque correcto desactiva la entrada anterior, guarda la referencia del paquete y conserva los ajustes, las Skills y la caché. Si vuelves a añadir el plugin manualmente, HolyCode lo trata como administrado por ti.

Comandos útiles

volver arriba

💾 Datos y persistencia

Todo el estado de OpenCode vive en un único bind mount en ./data/opencode. El contenedor es sin estado. El bind mount contiene todo lo que importa.

Reconstruye el contenedor cuando quieras. Ejecuta docker compose pull && docker compose up -d y tus sesiones, ajustes y configuraciones vuelven automáticamente.

Nota sobre SQLite WAL. La base de datos de sesiones usa Write-Ahead Logging. No copies el archivo .db mientras el contenedor esté en ejecución. Detén el contenedor primero si necesitas hacer copia de seguridad o migrar el archivo de base de datos.

Nota sobre almacenamiento en red. Si ./data/opencode está en un montaje de red CIFS/SMB (NAS, Synology, TrueNAS), el modo WAL de SQLite puede fallar porque SMB no soporta bloqueo de rango de bytes por defecto. HolyCode detecta esto al inicio y muestra una advertencia con la solución. Consulta la sección de Solución de problemas a continuación.

volver arriba

🔐 Permisos

HolyCode usa PUID y PGID para reasignar el usuario interno del contenedor para que coincida con el usuario del host. Esto significa que los archivos escritos en ./workspace son de tu propiedad, no de root.

Encuentra tus IDs en Linux y macOS:

id -u   # PUID
id -g   # PGID

En la mayoría de sistemas esto es 1000:1000. En macOS suele ser 501:20. Configúralos en tu archivo compose:

environment:
  - PUID=501
  - PGID=20

Si omites esto, los archivos de tu espacio de trabajo pueden ser propiedad de root y necesitarás sudo para editarlos desde el host.

volver arriba

⬆️ Actualizaciones

Detén el contenedor y haz una copia de seguridad de los volúmenes de inicio, caché y espacio de trabajo antes de descargar la última imagen.

Si actualizas desde una versión anterior a v1.1.3, descarga el perfil seccomp indicado arriba y agrega security_opt al servicio holycode antes de recrear el contenedor.

v1.2.9 mantiene Paperclip en 2026.831.1, por lo que no añade una migración de Paperclip ni cambia de forma predeterminada el ejecutor nativo. Para volver atrás, restaura los volúmenes de inicio, caché y espacio de trabajo intactos de antes de la actualización con la imagen 1.2.8; no reutilices volúmenes que ya se hayan iniciado con v1.2.9.

v1.1.9 migra Paperclip de 2026.824.1 a 2026.831.1 mediante las migraciones 0223–0230. Los campos retirados brandColor y attachmentMaxBytes se eliminan y las sesiones de inicio de sesión en curso se reinician; vuelve a iniciar sesión después de la actualización. Para volver atrás, restaura la copia intacta con la imagen 1.1.8. Nunca inicies 1.1.8 con una base de datos ya migrada por v1.1.9.

Paperclip migra de 2026.707.0 a 2026.722.0 en v1.1.4. Para volver atrás, usa la imagen 1.1.3 con volúmenes intactos de antes de la actualización a v1.1.4. Nunca inicies la imagen 1.1.3 con datos de Paperclip ya migrados por v1.1.4.

docker compose stop
docker compose pull
docker compose up -d

volver arriba

🛠 Solución de problemas

services:
  holycode:
    shm_size: 2g

id -u && id -g

environment:
  - PUID=1001   # reemplaza con tu UID real
  - PGID=1001   # reemplaza con tu GID real

ports:
  - "4097:4096"   # accede mediante http://localhost:4097

# Linux / macOS
lsof -i :4096

# Windows
netstat -ano | findstr :4096

docker compose logs -f holycode

security_opt:
  - seccomp=./config/chromium-seccomp.json

Failed to run the query 'PRAGMA journal_mode = WAL'

# Antes
//192.168.1.100/share /mnt/share cifs credentials=/etc/smbcreds,uid=1000,gid=1000 0 0

# Después — añade nobrl,mfsymlinks
//192.168.1.100/share /mnt/share cifs credentials=/etc/smbcreds,uid=1000,gid=1000,nobrl,mfsymlinks 0 0

sudo umount /mnt/share
sudo mount /mnt/share

volver arriba

🔨 Compilación local

Clona el repositorio, compila la imagen, sustitúyela en tu archivo compose.

git clone https://github.com/coderluii/holycode.git
cd holycode
docker build -t holycode:local .

Luego en tu docker-compose.yaml sustituye la imagen:

image: holycode:local

volver arriba

🤝 Contribuir

1. Haz un fork del repositorio
2. Crea una rama: git checkout -b feature/your-feature
3. Confirma tus cambios: git commit -m "feat: your feature"
4. Haz push: git push origin feature/your-feature
5. Abre un pull request

Consulta CONTRIBUTING.md para las pautas completas.

volver arriba

⭐ Soporte

Si HolyCode te ha ahorrado otra hora de configuración de entorno, aquí tienes cómo devolver el favor.

• Dale una estrella al repositorio en GitHub
• Compártelo con alguien que le resulte útil
• Buy Me A Coffee
• PayPal
• GitHub Sponsors

volver arriba

📄 Licencia

Licencia MIT - ver LICENSE.

volver arriba