Kubiya Control Plane API

A multi-tenant AI agent orchestration and management platform built with FastAPI, Temporal, and PostgreSQL.

Features

Multi-tenant Architecture: Manage multiple projects, teams, and agents
Workflow Orchestration: Temporal-based workflow execution
Flexible Agent Runtime: Support for multiple agent types and skills
Policy Enforcement: OPA-based policy engine for agent governance
Scalable Workers: Distributed worker architecture for agent execution
Context Management: Environment and team-specific context handling
LLM Integration: Support for multiple LLM providers via LiteLLM
Comprehensive APIs: RESTful APIs for all platform features

Installation

Using pip

pip install kubiya-control-plane-api

With optional dependencies

# For API server
pip install kubiya-control-plane-api[api]

# For worker runtime
pip install kubiya-control-plane-api[worker]

# For development
pip install kubiya-control-plane-api[dev]

# All dependencies
pip install kubiya-control-plane-api[all]

From source

git clone https://github.com/kubiyabot/agent-control-plane.git
cd agent-control-plane
pip install -e .

Quick Start

1. Set up environment variables

Create a .env file or set the following environment variables:

# Database Configuration
DATABASE_URL=postgresql://user:password@localhost:5432/control_plane

# Supabase (for serverless deployments)
SUPABASE_URL=your-supabase-url
SUPABASE_KEY=your-supabase-key

# Temporal Configuration
TEMPORAL_HOST=localhost:7233
TEMPORAL_NAMESPACE=default

# API Configuration
API_TITLE="Agent Control Plane"
API_VERSION="1.0.0"
ENVIRONMENT=development
LOG_LEVEL=info

# Security
SECRET_KEY=your-secret-key-here

# Optional: Kubiya Integration
KUBIYA_API_KEY=your-kubiya-api-key
KUBIYA_API_URL=https://api.kubiya.ai

2. Run database migrations

alembic upgrade head

3. Start the API server

uvicorn control_plane_api.app.main:app --host 0.0.0.0 --port 7777 --reload

The API will be available at http://localhost:7777

4. Access the API documentation

Open your browser and navigate to:

Swagger UI: http://localhost:7777/api/docs
ReDoc: http://localhost:7777/api/redoc

5. Start a worker

To process agent execution workflows:

kubiya-control-plane-worker

API Endpoints

Core Resources

Projects: /api/v1/projects - Multi-project management
Environments: /api/v1/environments - Environment configuration
Agents: /api/v1/agents - Agent management
Teams: /api/v1/teams - Team management
Workflows: /api/v1/workflows - Workflow definitions
Executions: /api/v1/executions - Execution tracking
Workers: /api/v1/workers - Worker registration and management

Skills and Policies

Skills: /api/v1/skills - Tool sets and definitions
Policies: /api/v1/policies - Policy management and enforcement

Integration

Secrets: /api/v1/secrets - Secrets management (proxies to Kubiya)
Integrations: /api/v1/integrations - Third-party integrations
Models: /api/v1/models - LLM model configuration

Utilities

Health: /api/health - Health check endpoint
Task Planning: /api/v1/task-planning - AI-powered task planning

Configuration

The application uses Pydantic Settings for configuration management. All settings can be configured via environment variables or a .env file.

Key Configuration Options

DATABASE_URL: PostgreSQL connection string
SUPABASE_URL, SUPABASE_KEY: Supabase configuration for serverless
TEMPORAL_HOST: Temporal server address
KUBIYA_API_KEY: Kubiya platform API key
SECRET_KEY: Secret key for JWT token signing
LOG_LEVEL: Logging level (debug, info, warning, error)
ENVIRONMENT: Deployment environment (development, staging, production)

Development

Install development dependencies

pip install -e ".[dev]"

Run tests

# All tests
pytest

# Unit tests only
pytest -m unit

# Integration tests
pytest -m integration

# With coverage
pytest --cov=control_plane_api --cov-report=html

Code formatting

# Format code with black
black .

# Lint with ruff
ruff check .

Database migrations

# Create a new migration
alembic revision --autogenerate -m "Description of changes"

# Apply migrations
alembic upgrade head

# Rollback migration
alembic downgrade -1

Architecture

Workflow Orchestration

The platform uses Temporal for reliable workflow execution:

Durable execution with automatic retries
Activity-based task decomposition
Support for long-running workflows
Built-in observability and monitoring

Multi-tenancy

Projects: Top-level isolation boundary
Environments: Isolated execution contexts within projects
Teams: Collaborative agent groups
Agents: Individual agent instances

Worker Architecture

Workers pull tasks from environment-specific queues and execute agent workflows using Temporal.

Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests and linting
Submit a pull request

License

GNU Affero General Public License v3.0 (AGPL-3.0) - see LICENSE file for details

Support

For issues and questions:

GitHub Issues: https://github.com/kubiyabot/agent-control-plane/issues
Email: support@kubiya.ai

Metadata

Release files for kubiya-control-plane-api 1.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kubiya-control-plane-api 1.0.2
File	Size	Uploaded
kubiya_control_plane_api-1.0.2.tar.gz	1.2 MB	Feb 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for kubiya-control-plane-api 1.0.2
File	Interpreter	ABI	Platform	Reset
kubiya_control_plane_api-1.0.2-py3-none-any.whl 1.4 MB Feb 12, 2026	Python 3	none	any	Details

Total release size: 2.6 MB

Release files / kubiya_control_plane_api-1.0.2.tar.gz

Download URL	kubiya_control_plane_api-1.0.2.tar.gz
Size	1.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`6aafbda6ec8b73c9e729a5fbe2f0465a5a7ef34b4657ee57a2ee036332f16404`
BLAKE2b-256 checksum How to use checksums	`b75669c3a83f217ce66db4c46f9df3523f77a2b540ae018874c35ccaae395ad9`
Upload date	Feb 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Release files / kubiya_control_plane_api-1.0.2-py3-none-any.whl

Download URL	kubiya_control_plane_api-1.0.2-py3-none-any.whl
Size	1.4 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`316c4b34658de5b22028ba4769c411b1a147f1bf0b0255706bf1fe0f59bd702e`
BLAKE2b-256 checksum How to use checksums	`5b445dd4170fa8707e45c5c508c81af79a908d3f8d7c04789dafd278cdcdb06b`
Upload date	Feb 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`