Skip to main content
Install and configure the Control Plane SDK for managing agents, context graph, and other organization resources.

​
Prerequisites

Before installing the SDK, ensure you have:
  • Python 3.8+ installed on your system
  • pip package manager
  • Kubiya Control Plane API Key from the Kubiya platform

​
Installation

​
Install via pip

pip install kubiya-sdk

​
Install from Source

git clone https://github.com/kubiyabot/sdk-py.git
cd sdk-py
pip install -e .

​
Optional Dependencies

# For development tools
pip install kubiya-sdk[dev]

# Install all extras
pip install kubiya-sdk[all]

​
Configuration

​
Get Your API Key

  1. Log in to the Kubiya platform
  2. Navigate to Settings → API Keys
  3. Create a new API key or copy an existing one

​
Configure Authentication

Configure the client directly in your Python code with your API key: 
from kubiya import ControlPlaneClient

client = ControlPlaneClient(
    api_key="your-api-key",  # Required
    base_url="https://control-plane.kubiya.ai"  # Optional, defaults to Kubiya cloud
)
Note: The api_key parameter is required. The base_url parameter is optional and defaults to the Kubiya cloud platform. Specify a custom base_url for on-premise deployments.

​
Verify Installation

​
Quick Test

Test your installation and connection: 
from kubiya import ControlPlaneClient

client = ControlPlaneClient(api_key="your-api-key")
status = client.health.check()
print(f"Status: {status['status']}")

​
Version Check

import kubiya
print(f"Kubiya SDK version: {kubiya.__version__}")

​
Feature Test

from kubiya import ControlPlaneClient

client = ControlPlaneClient(api_key="your-api-key")

# List agents
agents = client.agents.list()
print(f"Found {len(agents)} agents")

​
IDE Setup

​
VS Code

  1. Install the Python extension
  2. Add these settings to your workspace (.vscode/settings.json):
{
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "python.formatting.provider": "black",
    "python.analysis.typeCheckingMode": "basic"
}
  1. For better autocompletion, install type stubs:
pip install types-requests types-pyyaml

​
PyCharm

  1. Go to File → Settings → Project → Python Interpreter
  2. Add the kubiya-sdk package to your interpreter
  3. Enable type checking in Settings → Editor → Inspections → Python
  4. Configure code style to use Black formatter

​
Jupyter Notebooks

The SDK works great in Jupyter notebooks: 
pip install kubiya-sdk jupyter
jupyter notebook

# In your notebook
from kubiya import ControlPlaneClient

client = ControlPlaneClient(api_key="your-api-key")

# List organization resources
agents = client.agents.list()

print(f"Agents: {len(agents)}")

​
Docker Setup

​
Using Docker

Create a Dockerfile: 
FROM python:3.11-slim

RUN pip install kubiya-sdk

# Set environment variables
ENV KUBIYA_API_KEY=${KUBIYA_API_KEY}

# Copy your application code
COPY app/ /app/
WORKDIR /app

CMD ["python", "main.py"]

​
Docker Compose

Create a docker-compose.yml: 
version: '3.8'

services:
  kubiya-app:
    build: .
    environment:
      - KUBIYA_API_KEY=${KUBIYA_API_KEY}
    volumes:
      - ./app:/app
    command: python main.py
Run with: 
docker-compose up

​
Environment Variables

Configure your environment by creating a .env file: 
# Kubiya API Key (Required)
KUBIYA_API_KEY=your-kubiya-api-key

​
Development Setup

For SDK development and contributions:

​
Clone Repository

git clone https://github.com/kubiyabot/sdk-py.git
cd sdk-py

​
Create Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

​
Install Development Dependencies

pip install -e ".[dev]"

​
Run Tests

# Run unit tests
pytest tests/unit/

# Run integration tests (requires API key in test configuration)
pytest tests/integration/

# Run with coverage
pytest --cov=kubiya tests/

​
Troubleshooting

​
Common Issues

​
ImportError: No module named ‘kubiya’

Solution: Ensure the SDK is installed in your current Python environment 
pip list | grep kubiya
pip install kubiya-sdk

​
AuthenticationError: Invalid API key

Solution: Verify your API key is correct and passed to the ControlPlaneClient constructor 
from kubiya import ControlPlaneClient

# Ensure your API key is correct
client = ControlPlaneClient(api_key="your-correct-api-key")

​
ConnectionTimeout: Request timed out

Solution: Increase timeout or check network connectivity 
from kubiya import ControlPlaneClient

client = ControlPlaneClient(
    api_key="your-api-key",
    timeout=120  # 2 minutes
)

​
SSL Certificate Error

Solution: For development environments only (not recommended for production) 
import ssl
ssl._create_default_https_context = ssl._create_unverified_context

​
Enable Debug Logging

For troubleshooting, enable debug logging: 
import logging
logging.basicConfig(level=logging.DEBUG)

from kubiya import ControlPlaneClient
client = ControlPlaneClient(api_key="your-api-key")

​
Version Compatibility

Kubiya SDKPythonKubiya Platform
1.0.x3.8+v2.0+
0.9.x3.7+v1.5+

​
Next Steps

Now that you have the SDK installed:

Quick Start Guide

Build your first integration in minutes

Control Plane Client

Learn the Control Plane client services

Context Graph

Query entities and relationships

Examples

Explore real-world usage patterns