Instalação

Requisitos do Sistema

Hardware Recomendado

Dimensionado para o modo de sandbox local padrão (kodus-graph + contexto cross-file rodam dentro do container worker).

CPU: 2+ núcleos (4+ recomendado para repos acima de ~100k LOC)
RAM: 8GB+ (16GB recomendado ao rodar o sandbox local em repos grandes)
Armazenamento: 60GB+ de espaço livre (Postgres guarda o cache do AST graph; cresce com a quantidade de repos e volume de PRs)

Software Necessário

Docker (última versão estável) com plugin Compose
Nome de domínio ou IP fixo se você quer receber webhooks de provedores Git na nuvem (GitHub.com, GitLab.com, etc.)

Portas Necessárias

Mapeamentos padrão de porta no host — ajuste no .env em caso de conflito.

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

Serviços

O que ./scripts/install.sh sobe, baseado no seu .env.Core (sempre ligados):

api — backend principal
worker — jobs de code review
webhooks — receptor de webhooks de provedores Git
kodus-web — frontend Next.js
db_kodus_postgres, db_kodus_mongodb, rabbitmq — infraestrutura local. Pule com USE_LOCAL_DB=false / USE_LOCAL_RABBITMQ=false pra apontar pra instâncias gerenciadas.

Opcionais:

kodus-mcp-manager — broker do Model Context Protocol. Habilite com API_MCP_SERVER_ENABLED=true. Veja MCP Manager.
worker-analytics — ingestão do Cockpit (métricas DORA, PR classifier). Exclusivo do self-hosted Enterprise, não vem por padrão. Veja Analytics Worker.

Code review usa um AST graph + contexto cross-file que roda em um sandbox — local (default, dentro do worker) ou e2b (sandbox remoto pago). Veja Sandbox & AST Graph pra entender os modos, comportamento de cache, e quando escolher cada um.

Acesso à internet é necessário se você planeja conectar a serviços Git na nuvem (GitHub, GitLab, Bitbucket) ou provedores de LLM na nuvem (OpenAI, Anthropic, etc.). Para ferramentas Git auto-hospedadas e LLMs on-premise dentro da sua rede, o acesso externo à internet é opcional.

Configuração de Domínio (Opcional)

Se você planeja integrar o Kodus com provedores Git na nuvem (GitHub, GitLab ou Bitbucket), precisará de URLs públicas tanto para o Kodus Web App quanto para sua API. Isso permite que seu servidor receba webhooks para o correto funcionamento da Revisão de Código e garante o comportamento correto da aplicação. Recomendamos configurar dois subdomínios:

Um para o Aplicativo Web, ex.: kodus-web.seudominio.com.
Um para a API, ex.: kodus-api.seudominio.com.

Os webhooks são gerenciados por um serviço separado (porta 3332). Você pode:

Usar um subdomínio dedicado para webhooks, ex.: kodus-webhooks.seudominio.com, ou
Continuar usando o domínio da API e rotear /github/webhook, /gitlab/webhook, etc. para o serviço de webhooks no seu proxy reverso.

Ambos os subdomínios devem ter registros DNS A apontando para o endereço IP do seu servidor. Mais adiante neste guia, configuraremos um proxy reverso (Nginx) para rotear as requisições desses subdomínios para os serviços internos corretos. Esta configuração é essencial para a funcionalidade completa, incluindo webhooks e autenticação.

Nota: Se você estiver conectando apenas a ferramentas Git auto-hospedadas na sua rede e não precisar de acesso público ou webhooks, poderá usar uma configuração mais simples, mas este guia foca em implantações com acesso público.

Configuração

Clonar o repositório do instalador

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

Copiar o arquivo de ambiente de exemplo

cp .env.example .env

Gerar chaves seguras para as variáveis de ambiente necessárias

./generate-keys.sh

Editar o arquivo de ambiente

Edite o .env com seus valores usando seu editor de texto preferido.

nano .env

Consulte Configuração de Variáveis de Ambiente para instruções detalhadas.

Executar o instalador

./scripts/install.sh

Sucesso 🎉

Quando concluído, os serviços do Kodus devem estar rodando na sua máquina. Você pode verificar a instalação usando o seguinte script:

./scripts/doctor.sh

Acessar a interface web

Ao acessar a interface web pela primeira vez, você precisará:

Criar sua conta de administrador - Este será o primeiro usuário com acesso completo ao sistema
Configurar seu provedor Git - Conecte o GitHub, GitLab ou Bitbucket seguindo as instruções na tela
Selecionar repositórios para análise - Escolha quais repositórios de código o Kody irá revisar

Para etapas detalhadas sobre o processo de configuração inicial, consulte nosso Guia de Início Rápido.

Configuração das Variáveis de Ambiente

Use esta seção para preencher seu .env. Comece pelas URLs públicas, depois configure os bancos de dados e o RabbitMQ, e por fim adicione as configurações específicas dos provedores.

Configuração de Namespace

Estas configurações definem as URLs públicas e o binding de host utilizados pela aplicação web e pela API. Se não estiver usando o MCP Manager, você pode ignorar as entradas MCP aqui e o bloco completo abaixo.

WEB_HOSTNAME_API="kodus-api.yourdomain.com"    # Hostname público da API (ex.: kodus-api.yourdomain.com)
NEXTAUTH_URL="https://kodus-web.yourdomain.com" # URL base pública completa para a Aplicação Web (ex.: https://kodus-web.yourdomain.com)
API_HOST=0.0.0.0                              # Host da API (0.0.0.0 para desenvolvimento local)

# Necessário apenas se quiser usar os recursos MCP.
API_KODUS_SERVICE_MCP_MANAGER=http://kodus-mcp-manager:3101 # URL do MCP Manager
API_KODUS_MCP_SERVER_URL=http://kodus-api.yourdomain.com/mcp # URL do servidor MCP do Kodus

Configuração do Provedor de LLM

API_LLM_PROVIDER_MODEL="gpt-5"     # Modelo que você deseja usar
API_OPENAI_FORCE_BASE_URL="https://your-api.com/v1"  # URL do seu provedor de API
API_OPEN_AI_API_KEY="your-api-key"          # Chave de API do seu provedor

Consulte nossos guias específicos por modelo para instruções detalhadas de configuração com provedores populares como Novita, OpenAI, Anthropic e outros.

Configuração do Banco de Dados

Use contêineres locais para Postgres e MongoDB por padrão. Atualize as credenciais de acordo com seus requisitos de segurança.

# Use contêineres locais para Postgres e MongoDB
USE_LOCAL_DB=true

# Configurações do PostgreSQL
API_DATABASE_ENV="development"                # development, production, test
API_PG_DB_HOST=db_kodus_postgres              # Host do PostgreSQL
API_PG_DB_PORT=5432                          # Porta do PostgreSQL
API_PG_DB_USERNAME=kodusdev                  # Usuário do banco de dados
API_PG_DB_PASSWORD=                          # Senha do banco de dados
API_PG_DB_DATABASE=kodus_db                  # Nome do banco de dados

# Configurações do MongoDB
API_MG_DB_HOST=db_kodus_mongodb              # Host do MongoDB
API_MG_DB_PORT=27017                         # Porta do MongoDB
API_MG_DB_USERNAME=kodusdev                  # Usuário do banco de dados
API_MG_DB_PASSWORD=                          # Senha do banco de dados
API_MG_DB_DATABASE=kodus                     # Nome do banco de dados
API_MG_DB_PRODUCTION_CONFIG=''               # Configurações adicionais de produção

# SSL — o container local do Postgres não tem SSL. Esta flag global cobre
# TODAS as conexões (default + analytics). Se ficar false, a api entra em
# loop de retry tentando conectar com SSL.
API_DATABASE_DISABLE_SSL=true                # desativa SSL para o Postgres local

Para bancos de dados embutidos, deixe API_PG_DB_PASSWORD e API_MG_DB_PASSWORD em branco e rode ./scripts/generate-secrets.sh para gerá-los, ou defina os seus. Para bancos de dados externos, use a senha do banco de dados existente.

Configuração do RabbitMQ

O RabbitMQ é obrigatório na versão 2.0. Mantenha a URI sincronizada com os valores abaixo.

# Configuração do RabbitMQ
USE_LOCAL_RABBITMQ=true
RABBITMQ_HOSTNAME=rabbitmq                   # Hostname do RabbitMQ na rede Docker
RABBITMQ_DEFAULT_USER=kodus                  # Usuário do RabbitMQ (altere em produção)
RABBITMQ_DEFAULT_PASS=kodus                  # Senha do RabbitMQ (altere em produção)

# Mantenha a URI sincronizada com o usuário, senha e vhost acima
API_RABBITMQ_URI=amqp://kodus:kodus@rabbitmq:5672/kodus-ai # URI de conexão do RabbitMQ
API_RABBITMQ_ENABLED=true                    # RabbitMQ é obrigatório

Configuração do Worker

O container do worker precisa de um papel para saber qual carga processar. Self-hosted roda apenas o papel de revisão de código; o papel de analytics é exclusivo do cloud.

Deixar WORKER_ROLE em branco trava o worker no boot. Como é o worker quem cria as filas workflow.jobs.* na primeira conexão, a api e os webhooks passam a falhar todo evento de webhook com QueueBind 404.

# Papel do worker — obrigatório. Self-hosted = code-review.
WORKER_ROLE=code-review

Configuração do Provedor Git

Escolha e configure seu provedor Git preferido. Você pode configurar um ou mais provedores; para autenticação básica por token, você só precisa da URL do webhook.

Os webhooks são tratados por um serviço separado (porta 3332). Suas URLs de webhook devem alcançar esse serviço. Você pode usar um domínio dedicado para webhooks, ou manter o domínio da API e rotear os caminhos /.../webhook para o serviço de webhooks no seu proxy reverso. Usando OAuth do GitHub ou GitLab? Veja OAuth App do GitHub ou OAuth App do GitLab. Para configuração do GitHub App, veja GitHub App.

Github
GitLab
Bitbucket
Azure DevOps

# Necessário para autenticação baseada em token
API_GITHUB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/github/webhook"          # URL do webhook (use domínio de webhooks, ou domínio da API se roteado para o serviço de webhooks)

# Necessário para autenticação baseada em token
API_GITLAB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/gitlab/webhook"          # URL do webhook (use domínio de webhooks, ou domínio da API se roteado para o serviço de webhooks)

# Necessário para autenticação baseada em token
GLOBAL_BITBUCKET_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/bitbucket/webhook"    # URL do webhook (use domínio de webhooks, ou domínio da API se roteado para o serviço de webhooks)

# Necessário para autenticação baseada em token
GLOBAL_AZURE_REPOS_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/azure-repos/webhook"    # URL do webhook (use domínio de webhooks, ou domínio da API se roteado para o serviço de webhooks)

Configuração do MCP Manager

Necessário apenas se quiser usar o MCP Manager.

O MCP Manager é o serviço que conecta o Kody a ferramentas externas e as expõe na tela de Plugins. Consulte nossa documentação do MCP Manager para mais informações.

API_MCP_SERVER_ENABLED=false # Altere para true se quiser usar o MCP Manager
---
API_KODUS_SERVICE_MCP_MANAGER=http://kodus-mcp-manager:3101
API_KODUS_MCP_SERVER_URL=http://localhost:3001/mcp

# Configuração do 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=

Configuração de Serviços Externos (Opcional)

Estes serviços são opcionais, mas melhoram significativamente a qualidade da revisão de código do Kodus. Cada um requer a criação de uma conta e geração de uma chave de API.

E2B — Sandbox de Execução de Código

O E2B fornece um sandbox seguro que o Kodus usa para executar e validar código durante as revisões.

Crie uma conta em e2b.dev
Gere uma chave de API no seu painel
Adicione ao seu .env:

API_E2B_KEY=your-e2b-api-key

MorphLLM — Modelo de Edição de Código

MorphLLM é um modelo especializado para edição de código rápida e precisa. O Kodus o utiliza para aplicar sugestões de revisão com mais precisão.

Crie uma conta em morphllm.com
Gere uma chave de API no seu painel
Adicione ao seu .env:

API_MORPHLLM_API_KEY=your-morphllm-api-key

Precisa de ajuda?

Agende uma chamada com nosso fundador para obter ajuda com sua implantação.

Obtenha ajuda com nossa comunidade

Entre na nossa comunidade para obter ajuda com sua implantação.

Conceitos

Início Rápido Local

Implantar com Docker

Implantar com Kubernetes

Configuração de Provedores Git

Instalação

Requisitos do Sistema

Configuração de Domínio (Opcional)

Configuração

Configuração das Variáveis de Ambiente

Configuração de Namespace

Configuração do Provedor de LLM

Configuração do Banco de Dados

Configuração do RabbitMQ

Configuração do Worker

Configuração do Provedor Git

Configuração do MCP Manager

Configuração de Serviços Externos (Opcional)

Precisa de ajuda?

Obtenha ajuda com nossa comunidade

​Requisitos do Sistema

​Configuração de Domínio (Opcional)

​Configuração

​Configuração das Variáveis de Ambiente

​Configuração de Namespace

​Configuração do Provedor de LLM

​Configuração do Banco de Dados

​Configuração do RabbitMQ

​Configuração do Worker

​Configuração do Provedor Git

​Configuração do MCP Manager

​Configuração de Serviços Externos (Opcional)

Precisa de ajuda?

Obtenha ajuda com nossa comunidade

Requisitos do Sistema

Configuração de Domínio (Opcional)

Configuração

Configuração das Variáveis de Ambiente

Configuração de Namespace

Configuração do Provedor de LLM

Configuração do Banco de Dados

Configuração do RabbitMQ

Configuração do Worker

Configuração do Provedor Git

Configuração do MCP Manager

Configuração de Serviços Externos (Opcional)