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.
This guide walks you through setting up the Agent Control Plane locally for development purposes.
Prerequisites
- Docker and Docker Compose installed
Quick Start
Copy the example environment file:
cp env.local.example .env
.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>
2. Start the Services
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 |
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:
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:
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:
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
