> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Developers Guide

> Local development setup for the Agent Control Plane. Run the full stack with Docker Compose, configure environment variables, and use Makefile commands.

This guide walks you through setting up the Agent Control Plane locally for development purposes.

## Prerequisites

* **Docker** and **Docker Compose** installed

## Quick Start

### 1. Configure Environment Variables

Copy the example environment file:

```bash theme={null}
cp env.local.example .env
```

The `.env` file comes pre-configured with defaults for local development. Most values work out of the box, but you **must** fill in these required variables:

```bash theme={null}
# Required - LiteLLM Configuration
LITELLM_API_BASE=<your-litellm-api-base>
LITELLM_API_KEY=<your-litellm-api-key>

# Required - Kubiya API Key
KUBIYA_API_KEY=<your-kubiya-api-key>
```

All other values (database, Redis, Temporal) have sensible defaults for local development.

### 2. Start the Services

```bash theme={null}
make up
```

This command builds and starts all services. Database migrations run automatically on startup.

## Service URLs

Once running, the following services are available:

| Service                | URL                                                              | Description                                       |
| ---------------------- | ---------------------------------------------------------------- | ------------------------------------------------- |
| **API**                | [http://localhost:7777](http://localhost:7777)                   | Control Plane REST API                            |
| **API Docs (Swagger)** | [http://localhost:7777/api/docs](http://localhost:7777/api/docs) | Interactive API documentation                     |
| **Temporal UI**        | [http://localhost:8080](http://localhost:8080)                   | Workflow monitoring dashboard                     |
| **PostgreSQL**         | `localhost:5432`                                                 | Database (user: `postgres`, password: `postgres`) |
| **Redis**              | `localhost:6379`                                                 | Cache and message broker (password: `redis`)      |

## Makefile Commands

The project includes a comprehensive Makefile for common operations:

### Core Commands

| Command        | Description                               |
| -------------- | ----------------------------------------- |
| `make help`    | Display all available commands            |
| `make build`   | Build all Docker images                   |
| `make up`      | Start all services                        |
| `make down`    | Stop all services                         |
| `make restart` | Restart all services                      |
| `make logs`    | View logs from all services (follow mode) |
| `make ps`      | Show running containers                   |
| `make health`  | Check health status of all services       |
| `make clean`   | Remove all containers and volumes         |
| `make shell`   | Open a bash shell in the API container    |

### Database Migrations

| Command                                 | Description                     |
| --------------------------------------- | ------------------------------- |
| `make migrate`                          | Run pending database migrations |
| `make migrate-create MSG="description"` | Create a new migration          |
| `make migrate-downgrade`                | Rollback the last migration     |

**Example - Creating a new migration:**

```bash theme={null}
make migrate-create MSG="add user preferences table"
```

## Architecture Overview

The local development stack includes:

```
┌─────────────────────────────────────────────────────────────┐
│                    Docker Compose Stack                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────┐    ┌─────────────────┐                 │
│  │ Control Plane   │    │ Temporal Worker │                 │
│  │ API (:7777)     │◄───│                 │                 │
│  └────────┬────────┘    └────────┬────────┘                 │
│           │                      │                          │
│           ▼                      ▼                          │
│  ┌─────────────────┐    ┌─────────────────┐                 │
│  │ PostgreSQL      │    │ Temporal        │                 │
│  │ (:5432)         │    │ (:7233)         │                 │
│  └─────────────────┘    └────────┬────────┘                 │
│                                  │                          │
│  ┌─────────────────┐    ┌────────▼────────┐                 │
│  │ Redis           │    │ Temporal UI     │                 │
│  │ (:6379)         │    │ (:8080)         │                 │
│  └─────────────────┘    └─────────────────┘                 │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Services

* **Control Plane API** - FastAPI application serving the REST API
* **Temporal Worker** - Processes workflow executions
* **Temporal** - Workflow orchestration engine
* **Temporal UI** - Web interface for monitoring workflows
* **PostgreSQL** - Primary database
* **Redis** - Caching and session storage

## Environment Variables Reference

### Database Configuration

| Variable            | Default                                                            | Description            |
| ------------------- | ------------------------------------------------------------------ | ---------------------- |
| `POSTGRES_DB`       | `agent_control_plane`                                              | Database name          |
| `POSTGRES_USER`     | `postgres`                                                         | Database user          |
| `POSTGRES_PASSWORD` | `postgres`                                                         | Database password      |
| `POSTGRES_PORT`     | `5432`                                                             | Database port          |
| `DATABASE_URL`      | `postgresql://postgres:postgres@postgres:5432/agent_control_plane` | Full connection string |

### Redis Configuration

| Variable         | Default                       | Description            |
| ---------------- | ----------------------------- | ---------------------- |
| `REDIS_HOST`     | `redis`                       | Redis hostname         |
| `REDIS_PORT`     | `6379`                        | Redis port             |
| `REDIS_PASSWORD` | `redis`                       | Redis password         |
| `REDIS_DB`       | `0`                           | Redis database number  |
| `REDIS_URL`      | `redis://:redis@redis:6379/0` | Full connection string |

### Temporal Configuration

| Variable             | Default         | Description             |
| -------------------- | --------------- | ----------------------- |
| `TEMPORAL_HOST`      | `temporal:7233` | Temporal server address |
| `TEMPORAL_NAMESPACE` | `default`       | Temporal namespace      |
| `TEMPORAL_UI_PORT`   | `8080`          | Temporal UI port        |

### API Configuration

| Variable      | Default                               | Description             |
| ------------- | ------------------------------------- | ----------------------- |
| `API_HOST`    | `0.0.0.0`                             | API bind address        |
| `API_PORT`    | `7777`                                | API port                |
| `ENVIRONMENT` | `development`                         | Environment name        |
| `LOG_LEVEL`   | `debug`                               | Logging level           |
| `SECRET_KEY`  | `dev-secret-key-change-in-production` | Secret key for sessions |

### External Services (Required)

| Variable           | Default                 | Description          |
| ------------------ | ----------------------- | -------------------- |
| `LITELLM_API_BASE` | -                       | LiteLLM API base URL |
| `LITELLM_API_KEY`  | -                       | LiteLLM API key      |
| `KUBIYA_API_BASE`  | `https://api.kubiya.ai` | Kubiya API base URL  |
| `KUBIYA_API_KEY`   | -                       | Kubiya API key       |

### Temporal Worker Configuration

| Variable   | Default | Description             |
| ---------- | ------- | ----------------------- |
| `QUEUE_ID` | -       | Default worker queue ID |

### Optional Services

| Variable               | Default | Description                 |
| ---------------------- | ------- | --------------------------- |
| `ENFORCER_SERVICE_URL` | -       | Policy enforcer service URL |

## Development Workflow

### Viewing Logs

Follow logs from all services:

```bash theme={null}
make logs
```

Or view logs for a specific service:

```bash theme={null}
docker compose logs -f control-plane-api
```

### Accessing the Database

Connect to PostgreSQL:

```bash theme={null}
docker compose exec postgres psql -U postgres -d agent_control_plane
```

### Running Commands in the API Container

```bash theme={null}
make shell
# Now inside the container
python -c "from control_plane_api import models; print('Models loaded')"
```

### Restarting After Code Changes

The API container mounts the source code as a volume, so most changes are reflected immediately. For changes requiring a restart:

```bash theme={null}
make restart
```

## Troubleshooting

### Services Won't Start

1. Check if ports are already in use:
   ```bash theme={null}
   lsof -i :7777 -i :8080 -i :5432 -i :6379
   ```

2. Clean up and restart:
   ```bash theme={null}
   make clean
   make up
   ```

### Database Connection Issues

1. Verify PostgreSQL is healthy:
   ```bash theme={null}
   docker compose ps postgres
   ```

2. Check logs:
   ```bash theme={null}
   docker compose logs postgres
   ```

### Temporal Workflow Issues

1. Access the Temporal UI at [http://localhost:8080](http://localhost:8080)
2. Check worker logs:
   ```bash theme={null}
   docker compose logs temporal-worker
   ```

## Next Steps

* Explore the [API documentation](http://localhost:7777/api/docs)
* Monitor workflows in the [Temporal UI](http://localhost:8080)
* Review the API reference for available endpoints