Skip to main content

​
System Requirements

  • Docker (latest stable version)
  • Node.js (latest LTS version)
  • Yarn or NPM (latest stable version)
  • Domain name or fixed IP (for external deployments)
  • 3000: Kodus Web App
  • 3001: API
  • 3332: Webhooks
  • 5672, 15672, 15692: RabbitMQ (AMQP, management, metrics)
  • 3101: MCP Manager (API, metrics)
  • 5432: PostgreSQL - 27017: MongoDB
Internet access is required if you plan to connect to cloud-based Git services (GitHub, GitLab, Bitbucket) or cloud LLM providers (OpenAI, Anthropic, etc.). For self-hosted Git tools and on-prem LLMs within your network, external internet access is optional.

​
Domain Name Setup (Optional)

If you're planning to integrate Kodus with cloud-based Git providers (GitHub, GitLab, or Bitbucket), you'll need public-facing URLs for both the Kodus Web App and its API. This allows your server to receive webhooks for proper Code Review functionality and ensures correct application behavior. We recommend setting up two subdomains:
  • One for the Web Application, e.g., kodus-web.yourdomain.com.
  • One for the API, e.g., kodus-api.yourdomain.com.
Webhooks are handled by a separate service (port 3332). You can either:
  • Use a dedicated webhooks subdomain, e.g., kodus-webhooks.yourdomain.com, or
  • Keep using the API domain and route /github/webhook, /gitlab/webhook, etc. to the webhooks service in your reverse proxy.
Both subdomains should have DNS A records pointing to your server's IP address. Later in this guide, we will configure a reverse proxy (Nginx) to route requests to these subdomains to the correct internal services. This setup is essential for full functionality, including webhooks and authentication.
Note: If you're only connecting to self-hosted Git tools on your network and do not require public access or webhooks, you might be able to use a simpler setup, but this guide focuses on public-facing deployments.

​
Setup

1

Clone the installer repository

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

Copy the example environment file

cp .env.example .env
3

Generate secure keys for the required environment variables

./generate-keys.sh
4

Edit the environment file

Edit .env with your values using your preferred text editor.
nano .env
See Environment Variables Configuration for detailed instructions.
5

Run the installer

./scripts/install.sh
6

Success 🎉

When complete, Kodus Services should be running on your machine. You can verify your installation using the following script:
./scripts/doctor.sh
7

Access the web interface

Once you access the web interface for the first time, you'll need to:
  1. Create your admin account - This will be the first user with full system access
  2. Configure your Git provider - Connect GitHub, GitLab, or Bitbucket following the on-screen instructions
  3. Select repositories for analysis - Choose which code repositories Kody will review
For detailed steps on the initial configuration process, refer to our Getting Started Guide.

​
Environment Variables Configuration

Use this section to fill your .env. Start with the public URLs, then set up databases and RabbitMQ, and finally add provider-specific settings.

​
Namespace Configuration

These settings define the public URLs and host binding used by the web app and API. If you are not using MCP Manager, you can skip the MCP entries here and the full block below. 
WEB_HOSTNAME_API="kodus-api.yourdomain.com"    # Public API hostname (e.g., kodus-api.yourdomain.com)
NEXTAUTH_URL="https://kodus-web.yourdomain.com" # Full public base URL for the Web App (e.g., https://kodus-web.yourdomain.com)
API_HOST=0.0.0.0                              # API host (0.0.0.0 for local development)

# Only needed if you want to use MCP features.
API_KODUS_SERVICE_MCP_MANAGER=http://kodus-mcp-manager:3101 # MCP Manager URL
API_KODUS_MCP_SERVER_URL=http://kodus-api.yourdomain.com/mcp # Kodus MCP Server URL

​
LLM Provider Configuration

API_LLM_PROVIDER_MODEL="gpt-5"     # Model you want to use
API_OPENAI_FORCE_BASE_URL="https://your-api.com/v1"  # Your API provider URL
API_OPEN_AI_API_KEY="your-api-key"          # Your API provider key
Check our model-specific guides for detailed setup instructions with popular providers like Novita, OpenAI, Anthropic, and more.

​
Database configuration

Use local containers for Postgres and MongoDB by default. Update credentials to match your security requirements. 
# Use local containers for Postgres and MongoDB
USE_LOCAL_DB=true

# PostgreSQL Settings
API_DATABASE_ENV="development"                # development, production, test
API_PG_DB_HOST=db_kodus_postgres              # PostgreSQL host
API_PG_DB_PORT=5432                          # PostgreSQL port
API_PG_DB_USERNAME=kodusdev                  # Database username
API_PG_DB_PASSWORD=                          # Database password
API_PG_DB_DATABASE=kodus_db                  # Database name

# MongoDB Settings
API_MG_DB_HOST=db_kodus_mongodb              # MongoDB host
API_MG_DB_PORT=27017                         # MongoDB port
API_MG_DB_USERNAME=kodusdev                  # Database username
API_MG_DB_PASSWORD=                          # Database password
API_MG_DB_DATABASE=kodus                     # Database name
API_MG_DB_PRODUCTION_CONFIG=''               # Additional production settings

​
RabbitMQ configuration

RabbitMQ is required in 2.0. Keep the URI in sync with the values below. 
# RabbitMQ Configuration
USE_LOCAL_RABBITMQ=true
RABBITMQ_HOSTNAME=rabbitmq                   # RabbitMQ hostname in Docker network
RABBITMQ_DEFAULT_USER=kodus                  # RabbitMQ user (change in production)
RABBITMQ_DEFAULT_PASS=kodus                  # RabbitMQ password (change in production)

# Keep the URI in sync with the user, password, and vhost above
API_RABBITMQ_URI=amqp://kodus:kodus@rabbitmq:5672/kodus-ai # RabbitMQ connection URI
API_RABBITMQ_ENABLED=true                    # RabbitMQ is required

​
Git Provider Configuration

Choose and configure your preferred Git provider. You can set one or more providers; for basic token-based authentication, you only need the webhook URL.
Webhooks are handled by a separate service (port 3332). Your webhook URLs must reach that service. You can use a dedicated webhooks domain, or keep the API domain and route /.../webhook paths to the webhooks service in your reverse proxy. Using GitHub or GitLab OAuth? See GitHub OAuth App or GitLab OAuth App. For GitHub App setup, see GitHub App.
# Required for token-based authentication
API_GITHUB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/github/webhook"          # Webhook URL (use webhooks domain, or API domain if proxied to webhooks service)

​
MCP Manager Configuration

Only needed if you want to use MCP Manager.
MCP Manager is the service that connects Kody to external tools and exposes them in the Plugins screen. Check our MCP Manager documentation for more information. 
API_MCP_SERVER_ENABLED=false # Change to true if you want to use MCP Manager
---
API_KODUS_SERVICE_MCP_MANAGER=http://kodus-mcp-manager:3101
API_KODUS_MCP_SERVER_URL=http://localhost:3001/mcp

# MCP Manager Configuration
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=

​
AST Code Review Configuration

Only needed if you want to enable AST-powered code review.
The AST service parses, trims, and manipulates code files before they reach the review pipeline. This improves review quality and reduces token consumption. It is included in the installer and runs as a separate container. 
API_ENABLE_CODE_REVIEW_AST=false  # Set to true to enable AST-powered code review
API_SERVICE_AST_URL=              # Internal URL of the AST service
The AST service also has its own configuration block. These values are pre-configured by the installer but can be adjusted to match your environment: 
# KODUS_SERVICE_AST
NODE_ENV=development
API_NODE_ENV=development
API_LOG_PRETTY=true
API_LOG_LEVEL=info

CONTAINER_NAME=kodus-service-ast
API_PORT=3002

# PostgreSQL — keep in sync with your main database settings
API_DATABASE_ENV="development"
API_PG_DB_HOST=postgres
API_PG_DB_PORT=5432
API_PG_DB_USERNAME=                # Same as API_PG_DB_USERNAME
API_PG_DB_PASSWORD=                # Same as API_PG_DB_PASSWORD
API_PG_DB_DATABASE=kodus_db
API_PG_DB_SCHEMA=kodus_workflow

# RabbitMQ — keep in sync with your main RabbitMQ settings
RABBIT_URL=                        # e.g. amqp://user:pass@rabbitmq:5672/vhost
RABBIT_RETRY_QUEUE=ast.jobs.retry.q
RABBIT_RETRY_TTL_MS=60000
RABBIT_PREFETCH=1
RABBIT_PUBLISH_TIMEOUT_MS=5000
RABBIT_SAC=false

# LangChain (optional — for tracing)
LANGCHAIN_TRACING_V2=false
LANGCHAIN_API_KEY=
LANGCHAIN_PROJECT=kodus-service-ast

# Shared storage
SHARED_STORAGE_PATH=/shared

# S3 (optional)
S3_ENABLED=false
S3_BUCKET_NAME=
AWS_REGION=

# Graph build options
ENABLE_INCREMENTAL_GRAPH=false
ENABLE_GRAPH_BENCHMARK=false
ENABLE_LIGHTWEIGHT_GRAPH=false

​
External Services Configuration (Optional)

These services are optional but significantly improve Kodus’s code review quality. Each requires you to create an account and generate an API key.
E2B provides a secure sandbox that Kodus uses to run and validate code during reviews.
  1. Create an account at e2b.dev
  2. Generate an API key in your dashboard
  3. Add it to your .env:
API_E2B_KEY=your-e2b-api-key
MorphLLM is a specialized model for fast, accurate code editing. Kodus uses it to apply review suggestions more precisely.
  1. Create an account at morphllm.com
  2. Generate an API key in your dashboard
  3. Add it to your .env:
API_MORPHLLM_API_KEY=your-morphllm-api-key

Need help?

Schedule a call with our founder to get help with your deployment.

Get help with our community

Join our community to get help with your deployment.