Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.kodus.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Requisitos do Sistema

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)
  • 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.)
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)
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

1

Clonar o repositório do instalador

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

Copiar o arquivo de ambiente de exemplo

cp .env.example .env
3

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

./generate-keys.sh
4

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.
5

Executar o instalador

./scripts/install.sh
6

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
7

Acessar a interface web

Ao acessar a interface web pela primeira vez, você precisará:
  1. Criar sua conta de administrador - Este será o primeiro usuário com acesso completo ao sistema
  2. Configurar seu provedor Git - Conecte o GitHub, GitLab ou Bitbucket seguindo as instruções na tela
  3. 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

​
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 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.
# 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)

​
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_COMPOSIO_BASE_URL=https://backend.composio.dev/api/v3
API_MCP_MANAGER_COMPOSIO_API_KEY=
API_MCP_MANAGER_MCP_PROVIDERS=kodusmcp,composio,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.
O E2B fornece um sandbox seguro que o Kodus usa para executar e validar código durante as revisões.
  1. Crie uma conta em e2b.dev
  2. Gere uma chave de API no seu painel
  3. Adicione ao seu .env:
API_E2B_KEY=your-e2b-api-key
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.
  1. Crie uma conta em morphllm.com
  2. Gere uma chave de API no seu painel
  3. 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.