Developers Guide

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:

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:

# 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

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	Control Plane REST API
API Docs (Swagger)	http://localhost:7777/api/docs	Interactive API documentation
Temporal UI	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:

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:

make logs

Or view logs for a specific service:

docker compose logs -f control-plane-api

Accessing the Database

Connect to PostgreSQL:

docker compose exec postgres psql -U postgres -d agent_control_plane

Running Commands in the API Container

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:

make restart

Troubleshooting

Services Won’t Start

Check if ports are already in use:

lsof -i :7777 -i :8080 -i :5432 -i :6379

Clean up and restart:
make clean make up

Database Connection Issues

Verify PostgreSQL is healthy:
docker compose ps postgres
Check logs:
docker compose logs postgres

Temporal Workflow Issues

Access the Temporal UI at http://localhost:8080
Check worker logs:
docker compose logs temporal-worker

Next Steps

Explore the API documentation
Monitor workflows in the Temporal UI
Review the API reference for available endpoints

Introduction

Quick Start

Web Interface

Core Concepts

Infrastructure

Developers Guide

Prerequisites

Quick Start

1. Configure Environment Variables

2. Start the Services

Service URLs

Makefile Commands

Core Commands

Database Migrations

Architecture Overview

Services

Environment Variables Reference

Database Configuration

Redis Configuration

Temporal Configuration

API Configuration

External Services (Required)

Temporal Worker Configuration

Optional Services

Development Workflow

Viewing Logs

Accessing the Database

Running Commands in the API Container

Restarting After Code Changes

Troubleshooting

Services Won’t Start

Database Connection Issues

Temporal Workflow Issues

Next Steps

​Prerequisites

​Quick Start

​1. Configure Environment Variables

​2. Start the Services

​Service URLs

​Makefile Commands

​Core Commands

​Database Migrations

​Architecture Overview

​Services

​Environment Variables Reference

​Database Configuration

​Redis Configuration

​Temporal Configuration

​API Configuration

​External Services (Required)

​Temporal Worker Configuration

​Optional Services

​Development Workflow

​Viewing Logs

​Accessing the Database

​Running Commands in the API Container

​Restarting After Code Changes

​Troubleshooting

​Services Won’t Start

​Database Connection Issues

​Temporal Workflow Issues

​Next Steps

Prerequisites

Quick Start

1. Configure Environment Variables

2. Start the Services

Service URLs

Makefile Commands

Core Commands

Database Migrations

Architecture Overview

Services

Environment Variables Reference

Database Configuration

Redis Configuration

Temporal Configuration

API Configuration

External Services (Required)

Temporal Worker Configuration

Optional Services

Development Workflow

Viewing Logs

Accessing the Database

Running Commands in the API Container

Restarting After Code Changes

Troubleshooting

Services Won’t Start

Database Connection Issues

Temporal Workflow Issues

Next Steps