Local Quickstart

This guide is for local development purposes. For production deployment, please refer to the Deploy Kodus guide.

Local dev runs with API_CLOUD_MODE=false, which is the same mode as a self-hosted instance — and which means the daily anonymous heartbeat to telemetry.kodus.io is enabled by default. If you don’t want your local experiments showing up in the fleet, set KODUS_TELEMETRY_DISABLED=true in your .env. See Anonymous Telemetry for what is sent and how to inspect it.

Prerequisites

Node.js (LTS version)
Docker
Yarn or NPM
LLM API Keys

Running the project

Automated Setup (Recommended)
Manual Setup

For a quick and automated setup, use our setup script:

git clone https://github.com/kodustech/kodus-ai.git
cd kodus-ai
yarn setup

This script will automatically:

✅ Check all required dependencies (Node.js, Yarn, Docker, OpenSSL)
✅ Install project dependencies
✅ Create and configure the .env file
✅ Generate all required security keys automatically
✅ Set up Docker networks
✅ Provide clear next steps

Choose your LLM mode (required)

Select one mode and fill your .env before starting the services.

Fixed Mode (Recommended for Self-Hosted)
Automatic Mode (High Quality)

This is the simplest mode and recommended for self-hosted installations. You only need to configure a single LLM model.

# Fixed Mode Configuration
API_LLM_PROVIDER_MODEL="gpt-3.5-turbo"     # 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

This mode is ideal for self-hosted because:

Requires only a single API key
Works with any OpenAI-compatible API provider
Easier to configure and maintain

Model Configuration Guides

Check our model-specific guides for detailed setup instructions with popular providers like Novita, OpenAI, Anthropic, and more.

This mode uses multiple LLM models to achieve the best possible results. Requires more configuration but offers the highest quality analysis.

# Automatic Mode Configuration
API_OPEN_AI_API_KEY=                       # OpenAI API key
API_GOOGLE_AI_API_KEY=                     # Google AI API key
API_ANTHROPIC_API_KEY=                     # Anthropic API key
API_NOVITA_AI_API_KEY=                     # Novita AI API key
API_VERTEX_AI_API_KEY=                     # Vertex AI API key

This mode offers the best quality because:

Uses multiple specialized models
Our pipeline is optimized to extract the best from each model
Ideal for enterprise installations prioritizing quality

Next steps

Basic setup:

yarn docker:start
yarn migrate:dev
yarn seed

With external integrations (webhooks, etc.):

yarn docker:start
yarn migrate:dev
yarn seed
yarn tunnel  # Creates public endpoint for external services

Once everything is running, open http://localhost:3000 in your browser.

If you prefer to configure everything manually:

1. Clone the repository

git clone https://github.com/kodustech/kodus-ai.git

2. Install dependencies

yarn install

3. Configure environment variables

cp .env.example .env

4. Choose your LLM mode (required)

Select one mode and fill your .env before starting the services.

Fixed Mode (Recommended for Self-Hosted)
Automatic Mode (High Quality)

This is the simplest mode and recommended for self-hosted installations. You only need to configure a single LLM model.

# Fixed Mode Configuration
API_LLM_PROVIDER_MODEL="gpt-3.5-turbo"     # 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

This mode is ideal for self-hosted because:

Requires only a single API key
Works with any OpenAI-compatible API provider
Easier to configure and maintain

Model Configuration Guides

Check our model-specific guides for detailed setup instructions with popular providers like Novita, OpenAI, Anthropic, and more.

This mode uses multiple LLM models to achieve the best possible results. Requires more configuration but offers the highest quality analysis.

# Automatic Mode Configuration
API_OPEN_AI_API_KEY=                       # OpenAI API key
API_GOOGLE_AI_API_KEY=                     # Google AI API key
API_ANTHROPIC_API_KEY=                     # Anthropic API key
API_NOVITA_AI_API_KEY=                     # Novita AI API key
API_VERTEX_AI_API_KEY=                     # Vertex AI API key

This mode offers the best quality because:

Uses multiple specialized models
Our pipeline is optimized to extract the best from each model
Ideal for enterprise installations prioritizing quality

5. Generate Security Keys

Before configuring your environment variables, you’ll need to generate secure keys for JWT tokens and other security-related configurations:

# For most security keys (JWT secrets, etc.)
openssl rand -base64 32

# For crypto keys and code management secrets
openssl rand -hex 32

# For webhook tokens (URL-safe)
openssl rand -base64 32 | tr -d '=' | tr '/+' '_-'

You’ll need to generate values for these security keys:

JWT_SECRET (use openssl rand -base64 32)
JWT_REFRESH_SECRET (use openssl rand -base64 32)
CODE_MANAGEMENT_SECRET (use openssl rand -hex 32)
CODE_MANAGEMENT_WEBHOOK_TOKEN (use openssl rand -base64 32 | tr -d '=' | tr '/+' '_-')

6. Set up Docker networks

Create the required Docker networks:

docker network create kodus-backend-services || true
docker network create shared-network || true

7. Starting the development environment

Launch the services using Docker:

yarn docker:start

This command starts:

Kodus API
Worker (async jobs)
Webhooks service
Kodus Web Application
PostgreSQL database
MongoDB database
RabbitMQ
Required network configurations

To also create a public endpoint for external services:

yarn tunnel

8. First-time setup

If this is your first time running the project, execute the following commands:Run database migrations:

yarn migrate:dev

Seed initial data:

yarn seed

9. Service endpoints

Access the services at:

Web UI: http://localhost:3000
API: http://localhost:3001
RabbitMQ Management: http://localhost:15672
Debug Port: 9229

Development workflow

Basic Local Development

Start services: yarn docker:start
Run migrations: yarn migrate:dev
Load seed data: yarn seed
Open the app: Visit http://localhost:3000
Health check: yarn dev:health-check

Development with External Integrations

If you need to test integrations with external services (like Git webhooks):

Start services: yarn docker:start && yarn migrate:dev && yarn seed
Create tunnel: yarn tunnel (creates public endpoint)
Update webhook URLs: The tunnel command updates your .env automatically
Configure Git provider: Use the tunnel URL in your Git provider webhook settings
Test integration: Trigger webhooks and monitor logs

Tunnel Benefits:

Test real webhook integrations locally
Debug external service communications
Share your development environment with team members
Test mobile apps or other external clients

Troubleshooting

Quick Health Check

yarn dev:health-check

This comprehensive health check validates:

✅ Services: Kodus API, Worker, Webhooks, Web, PostgreSQL, MongoDB, RabbitMQ
🔌 Port availability: Web (3000), API (3001), PostgreSQL (5432), MongoDB (27017), RabbitMQ (5672/15672)
🗄️ Database setup: Migrations and seed data
🌐 API endpoints: Health endpoints and basic connectivity

Manual Verification

Check Web UI: Visit http://localhost:3000 in your browser
Check API health: Visit http://localhost:3001/health
Check RabbitMQ: Visit http://localhost:15672 (default credentials: guest/guest)
Verify database connections: Check the logs for successful database connections
Test webhook endpoints: Your Git provider webhooks should point to http://localhost:3332/[provider]/webhook (or to your API domain if a reverse proxy routes /.../webhook to the webhooks service)

Setup Script Issues

If the automated setup script (yarn setup) fails: Missing dependencies:

# Check if all required tools are installed
node --version
yarn --version
docker --version
openssl version

Permission issues with Docker:

# Add your user to the docker group (Linux/macOS)
sudo usermod -aG docker $USER
# Then log out and log back in

Network creation errors:

# Check if networks already exist
docker network ls | grep kodus
# Remove conflicting networks if needed
docker network rm kodus-backend-services shared-network

Common Issues

Port conflicts:

Ensure ports 3000 (Web), 3001 (API), 5432 (PostgreSQL), 27017 (MongoDB), and 5672/15672 (RabbitMQ) are available
Stop other services using these ports before starting Kodus

Environment variables not loading:

Verify your .env file exists in the project root
Check that there are no trailing spaces in variable assignments
Ensure all required security keys were generated properly

Health check failures:

Run yarn dev:health-check to get detailed diagnostics
Check if containers are fully started (wait 1-2 minutes after yarn docker:start)
Verify database migrations and seed data are loaded
Check API logs with yarn docker:logs for startup errors

API not responding:

The API takes time to fully initialize after container startup
Check if migrations and seed data are loaded
Verify the .env file has all required variables
Run health check to see which specific components are failing

Webhook issues with external services:

Use yarn tunnel to create a public endpoint for external webhooks
Update your Git provider webhook URLs to use the tunnel URL
Ensure the tunnel is running when testing webhook integrations
Check tunnel logs for connection issues

Concepts

Local Quickstart

Deploy with Docker

Git providers configuration

Local Quickstart

Prerequisites

Running the project

Choose your LLM mode (required)

Model Configuration Guides

Next steps

1. Clone the repository

2. Install dependencies

3. Configure environment variables

4. Choose your LLM mode (required)

Model Configuration Guides

5. Generate Security Keys

6. Set up Docker networks

7. Starting the development environment

8. First-time setup

9. Service endpoints

Development workflow

Basic Local Development

Development with External Integrations

Troubleshooting

Quick Health Check

Manual Verification

Setup Script Issues

Common Issues

Concepts

Local Quickstart

Deploy with Docker

Git providers configuration

Documentation Index

​Prerequisites

​Running the project

​Choose your LLM mode (required)

Model Configuration Guides

​Next steps

​1. Clone the repository

​2. Install dependencies

​3. Configure environment variables

​4. Choose your LLM mode (required)

Model Configuration Guides

​5. Generate Security Keys

​6. Set up Docker networks

​7. Starting the development environment

​8. First-time setup

​9. Service endpoints

​Development workflow

​Basic Local Development

​Development with External Integrations

​Troubleshooting

​Quick Health Check

​Manual Verification

​Setup Script Issues

​Common Issues

Prerequisites

Running the project

Choose your LLM mode (required)

Next steps

1. Clone the repository

2. Install dependencies

3. Configure environment variables

4. Choose your LLM mode (required)

5. Generate Security Keys

6. Set up Docker networks

7. Starting the development environment

8. First-time setup

9. Service endpoints

Development workflow

Basic Local Development

Development with External Integrations

Troubleshooting

Quick Health Check

Manual Verification

Setup Script Issues

Common Issues