Instalación

Requisitos del Sistema

Hardware Recomendado

Dimensionado para el modo de sandbox local por defecto (kodus-graph

contexto cross-file corren dentro del contenedor worker).

CPU: 2+ núcleos (4+ recomendado para repos arriba de ~100k LOC)
RAM: 8GB+ (16GB recomendado al ejecutar el sandbox local en repos grandes)
Almacenamiento: 60GB+ de espacio libre (Postgres guarda el caché del AST graph; crece con la cantidad de repos y volumen de PRs)

Software Requerido

Docker (última versión estable) con el plugin Compose
Nombre de dominio o IP fija si quieres recibir webhooks de proveedores Git en la nube (GitHub.com, GitLab.com, etc.)

Puertos Requeridos

Mapeos por defecto de puertos del host — ajusta en .env si hay conflicto.

3000 — Kodus Web App
3001 — API
3332 — Webhooks
5432 — PostgreSQL
27017 — MongoDB
5672, 15672, 15692 — RabbitMQ (AMQP, panel, métricas)
3101 — MCP Manager (solo si API_MCP_SERVER_ENABLED=true)

Servicios

Lo que ./scripts/install.sh levanta, basado en tu .env.Core (siempre activos):

api — backend principal
worker — jobs de code review
webhooks — receptor de webhooks de proveedores Git
kodus-web — frontend Next.js
db_kodus_postgres, db_kodus_mongodb, rabbitmq — infraestructura local. Sáltalo con USE_LOCAL_DB=false / USE_LOCAL_RABBITMQ=false para apuntar a instancias gestionadas.

Opcionales:

kodus-mcp-manager — broker del Model Context Protocol. Habilita con API_MCP_SERVER_ENABLED=true. Ver MCP Manager.
worker-analytics — ingestión del Cockpit (métricas DORA, classifier de PR). Exclusivo del self-hosted Enterprise, no se activa por defecto. Ver Analytics Worker.

Code review usa un AST graph + contexto cross-file que corre en un sandbox — local (default, dentro del worker) o e2b (sandbox remoto pago). Ver Sandbox & AST Graph para los modos, comportamiento de caché, y cuándo elegir cada uno.

Se requiere acceso a internet si planeas conectarte a servicios Git en la nube (GitHub, GitLab, Bitbucket) o proveedores de LLM en la nube (OpenAI, Anthropic, etc.). Para herramientas Git auto-alojadas y LLMs on-premise dentro de tu red, el acceso externo a internet es opcional.

Configuración de Dominio (Opcional)

Si planeas integrar Kodus con proveedores Git en la nube (GitHub, GitLab o Bitbucket), necesitarás URLs públicas tanto para la aplicación web de Kodus como para su API. Esto permite que tu servidor reciba webhooks para el correcto funcionamiento de la Revisión de Código y garantiza el comportamiento correcto de la aplicación. Recomendamos configurar dos subdominios:

Uno para la Aplicación Web, por ejemplo, kodus-web.tudominio.com.
Uno para la API, por ejemplo, kodus-api.tudominio.com.

Los webhooks son gestionados por un servicio separado (puerto 3332). Puedes:

Usar un subdominio dedicado para webhooks, por ejemplo, kodus-webhooks.tudominio.com, o
Seguir usando el dominio de la API y enrutar /github/webhook, /gitlab/webhook, etc. al servicio de webhooks en tu proxy inverso.

Ambos subdominios deben tener registros DNS A apuntando a la dirección IP de tu servidor. Más adelante en esta guía, configuraremos un proxy inverso (Nginx) para enrutar las solicitudes de estos subdominios a los servicios internos correctos. Esta configuración es esencial para la funcionalidad completa, incluyendo webhooks y autenticación.

Nota: Si solo te conectas a herramientas Git auto-alojadas en tu red y no necesitas acceso público ni webhooks, podrías usar una configuración más simple, pero esta guía se centra en despliegues con acceso público.

Configuración

Clonar el repositorio del instalador

git clone https://github.com/kodustech/kodus-installer.git
cd kodus-installer

Copiar el archivo de entorno de ejemplo

cp .env.example .env

Generar claves seguras para las variables de entorno requeridas

./generate-keys.sh

Editar el archivo de entorno

Edita .env con tus valores usando tu editor de texto preferido.

nano .env

Consulta Configuración de Variables de Entorno para instrucciones detalladas.

Ejecutar el instalador

./scripts/install.sh

¡Éxito! 🎉

Una vez completado, los servicios de Kodus deberían estar ejecutándose en tu máquina. Puedes verificar la instalación con el siguiente script:

./scripts/doctor.sh

Acceder a la interfaz web

Al acceder a la interfaz web por primera vez, necesitarás:

Crear tu cuenta de administrador - Este será el primer usuario con acceso completo al sistema
Configurar tu proveedor Git - Conecta GitHub, GitLab o Bitbucket siguiendo las instrucciones en pantalla
Seleccionar repositorios para análisis - Elige qué repositorios de código revisará Kody

Para pasos detallados sobre el proceso de configuración inicial, consulta nuestra Guía de Inicio Rápido.

Configuración de variables de entorno

Usa esta sección para completar tu .env. Comienza con las URLs públicas, luego configura las bases de datos y RabbitMQ, y finalmente agrega la configuración específica de cada proveedor.

Configuración de espacio de nombres

Estas configuraciones definen las URLs públicas y el enlace de host utilizados por la aplicación web y la API. Si no usas MCP Manager, puedes omitir las entradas de MCP aquí y el bloque completo a continuación.

WEB_HOSTNAME_API="kodus-api.yourdomain.com"    # Hostname público de la API (ej., kodus-api.yourdomain.com)
NEXTAUTH_URL="https://kodus-web.yourdomain.com" # URL base pública completa para la aplicación web (ej., https://kodus-web.yourdomain.com)
API_HOST=0.0.0.0                              # Host de la API (0.0.0.0 para desarrollo local)

# Solo necesario si quieres usar las funcionalidades de MCP.
API_KODUS_SERVICE_MCP_MANAGER=http://kodus-mcp-manager:3101 # URL del MCP Manager
API_KODUS_MCP_SERVER_URL=http://kodus-api.yourdomain.com/mcp # URL del servidor MCP de Kodus

Configuración del proveedor LLM

API_LLM_PROVIDER_MODEL="gpt-5"     # Modelo que deseas utilizar
API_OPENAI_FORCE_BASE_URL="https://your-api.com/v1"  # URL de tu proveedor de API
API_OPEN_AI_API_KEY="your-api-key"          # Clave de tu proveedor de API

Consulta nuestras guías específicas por modelo para obtener instrucciones detalladas de configuración con proveedores populares como Novita, OpenAI, Anthropic y más.

Configuración de base de datos

Usa contenedores locales para Postgres y MongoDB de forma predeterminada. Actualiza las credenciales para que cumplan con tus requisitos de seguridad.

# Usar contenedores locales para Postgres y MongoDB
USE_LOCAL_DB=true

# Configuración de PostgreSQL
API_DATABASE_ENV="development"                # development, production, test
API_PG_DB_HOST=db_kodus_postgres              # Host de PostgreSQL
API_PG_DB_PORT=5432                          # Puerto de PostgreSQL
API_PG_DB_USERNAME=kodusdev                  # Nombre de usuario de la base de datos
API_PG_DB_PASSWORD=                          # Contraseña de la base de datos
API_PG_DB_DATABASE=kodus_db                  # Nombre de la base de datos

# Configuración de MongoDB
API_MG_DB_HOST=db_kodus_mongodb              # Host de MongoDB
API_MG_DB_PORT=27017                         # Puerto de MongoDB
API_MG_DB_USERNAME=kodusdev                  # Nombre de usuario de la base de datos
API_MG_DB_PASSWORD=                          # Contraseña de la base de datos
API_MG_DB_DATABASE=kodus                     # Nombre de la base de datos
API_MG_DB_PRODUCTION_CONFIG=''               # Configuración adicional de producción

# SSL — el contenedor local de Postgres no usa SSL. Este switch global
# cubre TODAS las conexiones (default + analytics). Si queda false, la api
# entra en un bucle de reintentos intentando conectarse con SSL.
API_DATABASE_DISABLE_SSL=true                # desactiva SSL para el Postgres local

Para bases de datos integradas, deja API_PG_DB_PASSWORD y API_MG_DB_PASSWORD en blanco y ejecuta ./scripts/generate-secrets.sh para generarlas, o define las tuyas. Para bases de datos externas, usa la contraseña de la base de datos existente.

Configuración de RabbitMQ

RabbitMQ es obligatorio en la versión 2.0. Mantén la URI sincronizada con los valores a continuación.

# Configuración de RabbitMQ
USE_LOCAL_RABBITMQ=true
RABBITMQ_HOSTNAME=rabbitmq                   # Hostname de RabbitMQ en la red Docker
RABBITMQ_DEFAULT_USER=kodus                  # Usuario de RabbitMQ (cambiar en producción)
RABBITMQ_DEFAULT_PASS=kodus                  # Contraseña de RabbitMQ (cambiar en producción)

# Mantén la URI sincronizada con el usuario, contraseña y vhost de arriba
API_RABBITMQ_URI=amqp://kodus:kodus@rabbitmq:5672/kodus-ai # URI de conexión a RabbitMQ
API_RABBITMQ_ENABLED=true                    # RabbitMQ es obligatorio

Configuración del worker

El contenedor del worker necesita un rol para saber qué carga manejar. Self-hosted solo ejecuta el rol de revisión de código; el rol de analytics es exclusivo de cloud.

Dejar WORKER_ROLE vacío hace que el worker falle al iniciar. Como es el worker quien crea las colas workflow.jobs.* en la primera conexión, la api y los webhooks luego fallan cada evento de webhook con QueueBind 404.

# Rol del worker — requerido. Self-hosted = code-review.
WORKER_ROLE=code-review

Configuración del proveedor Git

Elige y configura tu proveedor Git preferido. Puedes configurar uno o más proveedores; para la autenticación básica basada en token, solo necesitas la URL del webhook.

Los webhooks son gestionados por un servicio separado (puerto 3332). Las URLs de tus webhooks deben llegar a ese servicio. Puedes usar un dominio dedicado para webhooks, o mantener el dominio de la API y enrutar las rutas /.../webhook al servicio de webhooks en tu proxy inverso. ¿Usas OAuth de GitHub o GitLab? Consulta OAuth App de GitHub o OAuth App de GitLab. Para la configuración de GitHub App, consulta GitHub App.

Github
GitLab
Bitbucket
Azure DevOps

# Requerido para autenticación basada en token
API_GITHUB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/github/webhook"          # URL del webhook (usa el dominio de webhooks, o el dominio de la API si se enruta al servicio de webhooks)

# Requerido para autenticación basada en token
API_GITLAB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/gitlab/webhook"          # URL del webhook (usa el dominio de webhooks, o el dominio de la API si se enruta al servicio de webhooks)

# Requerido para autenticación basada en token
GLOBAL_BITBUCKET_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/bitbucket/webhook"    # URL del webhook (usa el dominio de webhooks, o el dominio de la API si se enruta al servicio de webhooks)

# Requerido para autenticación basada en token
GLOBAL_AZURE_REPOS_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/azure-repos/webhook"    # URL del webhook (usa el dominio de webhooks, o el dominio de la API si se enruta al servicio de webhooks)

Configuración del MCP Manager

Solo necesario si deseas usar MCP Manager.

MCP Manager es el servicio que conecta Kody con herramientas externas y las expone en la pantalla de Plugins. Consulta nuestra documentación de MCP Manager para más información.

API_MCP_SERVER_ENABLED=false # Cambiar a true si deseas usar MCP Manager
---
API_KODUS_SERVICE_MCP_MANAGER=http://kodus-mcp-manager:3101
API_KODUS_MCP_SERVER_URL=http://localhost:3001/mcp

# Configuración de MCP Manager
API_MCP_MANAGER_LOG_LEVEL=info
API_MCP_MANAGER_PORT=3101
API_MCP_MANAGER_NODE_ENV=development
API_MCP_MANAGER_DATABASE_ENV=development
API_MCP_MANAGER_CORS_ORIGINS=*
API_MCP_MANAGER_JWT_SECRET=
API_MCP_MANAGER_MCP_PROVIDERS=kodusmcp,custom
API_MCP_MANAGER_REDIRECT_URI=http://localhost:3000/setup/mcp/oauth
API_MCP_MANAGER_PG_DB_SCHEMA=mcp-manager
API_MCP_MANAGER_ENCRYPTION_SECRET=

Configuración de servicios externos (opcional)

Estos servicios son opcionales pero mejoran significativamente la calidad de la revisión de código de Kodus. Cada uno requiere crear una cuenta y generar una clave de API.

E2B — Sandbox de ejecución de código

E2B proporciona un sandbox seguro que Kodus usa para ejecutar y validar código durante las revisiones.

Crea una cuenta en e2b.dev
Genera una clave de API en tu panel de control
Agrégala a tu .env:

API_E2B_KEY=your-e2b-api-key

MorphLLM — Modelo de edición de código

MorphLLM es un modelo especializado para la edición de código rápida y precisa. Kodus lo utiliza para aplicar sugerencias de revisión con mayor precisión.

Crea una cuenta en morphllm.com
Genera una clave de API en tu panel de control
Agrégala a tu .env:

API_MORPHLLM_API_KEY=your-morphllm-api-key

¿Necesitas ayuda?

Programa una llamada con nuestro fundador para obtener ayuda con tu despliegue.

Obtén ayuda en nuestra comunidad

Únete a nuestra comunidad para obtener ayuda con tu despliegue.

Conceptos

Inicio Rápido Local

Despliegue con Docker

Desplegar con Kubernetes

Configuración de Proveedores Git

Instalación

Requisitos del Sistema

Configuración de Dominio (Opcional)

Configuración

Configuración de variables de entorno

Configuración de espacio de nombres

Configuración del proveedor LLM

Configuración de base de datos

Configuración de RabbitMQ

Configuración del worker

Configuración del proveedor Git

Configuración del MCP Manager

Configuración de servicios externos (opcional)

¿Necesitas ayuda?

Obtén ayuda en nuestra comunidad

​Requisitos del Sistema

​Configuración de Dominio (Opcional)

​Configuración

​Configuración de variables de entorno

​Configuración de espacio de nombres

​Configuración del proveedor LLM

​Configuración de base de datos

​Configuración de RabbitMQ

​Configuración del worker

​Configuración del proveedor Git

​Configuración del MCP Manager

​Configuración de servicios externos (opcional)

¿Necesitas ayuda?

Obtén ayuda en nuestra comunidad

Requisitos del Sistema

Configuración de Dominio (Opcional)

Configuración

Configuración de variables de entorno

Configuración de espacio de nombres

Configuración del proveedor LLM

Configuración de base de datos

Configuración de RabbitMQ

Configuración del worker

Configuración del proveedor Git

Configuración del MCP Manager

Configuración de servicios externos (opcional)