Skip to main content
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:
ServiceURLDescription
APIhttp://localhost:7777Control Plane REST API
API Docs (Swagger)http://localhost:7777/api/docsInteractive API documentation
Temporal UIhttp://localhost:8080Workflow monitoring dashboard
PostgreSQLlocalhost:5432Database (user: postgres, password: postgres)
Redislocalhost:6379Cache and message broker (password: redis)

​
Makefile Commands

The project includes a comprehensive Makefile for common operations:

​
Core Commands

CommandDescription
make helpDisplay all available commands
make buildBuild all Docker images
make upStart all services
make downStop all services
make restartRestart all services
make logsView logs from all services (follow mode)
make psShow running containers
make healthCheck health status of all services
make cleanRemove all containers and volumes
make shellOpen a bash shell in the API container

​
Database Migrations

CommandDescription
make migrateRun pending database migrations
make migrate-create MSG="description"Create a new migration
make migrate-downgradeRollback 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

VariableDefaultDescription
POSTGRES_DBagent_control_planeDatabase name
POSTGRES_USERpostgresDatabase user
POSTGRES_PASSWORDpostgresDatabase password
POSTGRES_PORT5432Database port
DATABASE_URLpostgresql://postgres:postgres@postgres:5432/agent_control_planeFull connection string

​
Redis Configuration

VariableDefaultDescription
REDIS_HOSTredisRedis hostname
REDIS_PORT6379Redis port
REDIS_PASSWORDredisRedis password
REDIS_DB0Redis database number
REDIS_URLredis://:redis@redis:6379/0Full connection string

​
Temporal Configuration

VariableDefaultDescription
TEMPORAL_HOSTtemporal:7233Temporal server address
TEMPORAL_NAMESPACEdefaultTemporal namespace
TEMPORAL_UI_PORT8080Temporal UI port

​
API Configuration

VariableDefaultDescription
API_HOST0.0.0.0API bind address
API_PORT7777API port
ENVIRONMENTdevelopmentEnvironment name
LOG_LEVELdebugLogging level
SECRET_KEYdev-secret-key-change-in-productionSecret key for sessions

​
External Services (Required)

VariableDefaultDescription
LITELLM_API_BASE-LiteLLM API base URL
LITELLM_API_KEY-LiteLLM API key
KUBIYA_API_BASEhttps://api.kubiya.aiKubiya API base URL
KUBIYA_API_KEY-Kubiya API key

​
Temporal Worker Configuration

VariableDefaultDescription
QUEUE_ID-Default worker queue ID

​
Optional Services

VariableDefaultDescription
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

  1. Check if ports are already in use: 
    lsof -i :7777 -i :8080 -i :5432 -i :6379
  2. Clean up and restart: 
    make clean
make up

​
Database Connection Issues

  1. Verify PostgreSQL is healthy: 
    docker compose ps postgres
  2. Check logs: 
    docker compose logs postgres

​
Temporal Workflow Issues

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

​
Next Steps