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

# Local Quickstart

> Get Kodus running on your local machine — API, Worker, Webhooks, Web UI, and all dependencies in one command.

> [!NOTE]
>
> This guide is for local development purposes. For production deployment,
> please refer to the [Deploy Kodus](https://docs.kodus.io/en/how_to_deploy/deploy_kodus/generic_vm.md)
> guide.

> [!NOTE]
>
> 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](https://docs.kodus.io/en/how_to_deploy/deploy_kodus/telemetry.md)
> for what is sent and how to inspect it.

## Prerequisites

* Node.js (see `.nvmrc` for the pinned version)
* pnpm
* Docker
* OpenSSL
* LLM API Keys

> [!NOTE]
>
> kodus-ai is a pnpm workspace — `pnpm-lock.yaml` is the only lockfile in the repo. npm and yarn
> are not supported for local development.

## Running the project

> [tab] Automated Setup (Recommended)
>
> For a quick and automated setup, use our setup script:
>
> ```bash theme={null}
> git clone https://github.com/kodustech/kodus-ai.git
> cd kodus-ai
> pnpm run setup
> ```
>
> > [!WARNING]
> >
> > Use `pnpm run setup`, not `pnpm setup` — the latter is pnpm's own built-in command for
> > configuring its home directory and will not run the project script.
>
> This script will automatically:
>
> * ✅ Check all required dependencies (Node.js, pnpm, 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.
>
> <Snippet file="llm-api-keys.mdx" />
>
> ### Next steps
>
> **Basic setup:**
>
> ```bash theme={null}
> pnpm run docker:start
> ```
>
> **With external integrations (webhooks, etc.):**
>
> ```bash theme={null}
> pnpm run docker:start
> pnpm run tunnel  # Creates public endpoint for external services
> ```
>
> > [!NOTE]
> >
> > Database migrations and seeds run **automatically** on container boot — the dev compose
> > file defaults `RUN_MIGRATIONS` and `RUN_SEEDS` to `true`. You don't need a separate step.
> >
> > If you set them to `false` to manage them yourself, run `pnpm run migration:run` and
> > `pnpm run seed` from the host.
>
> Once everything is running, open **[http://localhost:3000](http://localhost:3000)** in your browser.

> [tab] Manual Setup
>
> If you prefer to configure everything manually:
>
> ### 1. Clone the repository
>
> ```bash theme={null}
> git clone https://github.com/kodustech/kodus-ai.git
> ```
>
> ### 2. Install dependencies
>
> ```bash theme={null}
> pnpm install
> ```
>
> ### 3. Configure environment variables
>
> ```bash theme={null}
> cp .env.example .env
> ```
>
> ### 4. Choose your LLM mode (required)
>
> Select one mode and fill your .env before starting the services.
>
> <Snippet file="llm-api-keys.mdx" />
>
> ### 5. Generate Security Keys
>
> Before configuring your environment variables, you'll need to generate secure keys for JWT tokens and other security-related configurations:
>
> ```bash theme={null}
> # 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:
>
> * `API_JWT_SECRET` (use `openssl rand -base64 32`)
> * `API_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:
>
> ```bash theme={null}
> docker network create kodus-backend-services || true
> docker network create shared-network || true
> ```
>
> ### 7. Starting the development environment
>
> Launch the services using Docker:
>
> ```bash theme={null}
> pnpm run 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:
>
> ```bash theme={null}
> pnpm run tunnel
> ```
>
> ### 8. First-time setup
>
> Nothing to do — the API container runs migrations and seeds on boot, because
> `docker-compose.dev.yml` defaults `RUN_MIGRATIONS` and `RUN_SEEDS` to `true`.
>
> > [accordion] Running migrations manually
> >
> > If you set `RUN_MIGRATIONS=false` / `RUN_SEEDS=false` in your `.env` (for example to
> > control them yourself), run them from the host with:
> >
> > ```bash theme={null}
> > pnpm run migration:run   # OLTP database
> > pnpm run seed            # initial data
> > ```
> >
> > There are separate commands for the other datastores:
> >
> > ```bash theme={null}
> > pnpm run analytics:migration:run     # analytics warehouse
> > pnpm run mcp-manager:migration:run   # MCP manager
> > pnpm run mongo:migrate               # MongoDB
> > ```
>
> ### 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

1. **Start services**: `pnpm run docker:start` (migrations and seeds run automatically)
2. **Open the app**: Visit `http://localhost:3000`
3. **Health check**: `pnpm run dev:health-check`

### Development with External Integrations

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

1. **Start services**: `pnpm run docker:start`
2. **Create tunnel**: `pnpm run tunnel` (creates public endpoint)
3. **Update webhook URLs**: The tunnel command updates your `.env` automatically
4. **Configure Git provider**: Use the tunnel URL in your Git provider webhook settings
5. **Test integration**: Trigger webhooks and monitor logs

> [!NOTE]
>
> **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

```bash theme={null}
pnpm run 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

1. **Check Web UI**: Visit `http://localhost:3000` in your browser
2. **Check API health**: Visit `http://localhost:3001/health`
3. **Check RabbitMQ**: Visit `http://localhost:15672` (default credentials: `guest`/`guest`)
4. **Verify database connections**: Check the logs for successful database connections
5. **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 (`pnpm run setup`) fails:

**Missing dependencies:**

```bash theme={null}
# Check if all required tools are installed
node --version
pnpm --version
docker --version
openssl version
```

**Permission issues with Docker:**

```bash theme={null}
# Add your user to the docker group (Linux/macOS)
sudo usermod -aG docker $USER
# Then log out and log back in
```

**Network creation errors:**

```bash theme={null}
# 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 `pnpm run dev:health-check` to get detailed diagnostics
* Check if containers are fully started (wait 1-2 minutes after `pnpm run docker:start`)
* Verify database migrations and seed data are loaded
* Check API logs with `pnpm run 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 `pnpm run 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.