Installation & Setup

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

Log in to the Kubiya platform
Navigate to Settings → API Keys
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

Install the Python extension
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"
}

For better autocompletion, install type stubs:

pip install types-requests types-pyyaml

PyCharm

Go to File → Settings → Project → Python Interpreter
Add the kubiya-sdk package to your interpreter
Enable type checking in Settings → Editor → Inspections → Python
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 SDK	Python	Kubiya Platform
1.0.x	3.8+	v2.0+
0.9.x	3.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

​Prerequisites

​Installation

​Install via pip

​Install from Source

​Optional Dependencies

​Configuration

​Get Your API Key

​Configure Authentication

​Verify Installation

​Quick Test

​Version Check

​Feature Test

​IDE Setup

​VS Code

​PyCharm

​Jupyter Notebooks

​Docker Setup

​Using Docker

​Docker Compose

​Environment Variables

​Development Setup

​Clone Repository

​Create Virtual Environment

​Install Development Dependencies

​Run Tests

​Troubleshooting

​Common Issues

​ImportError: No module named ‘kubiya’

​AuthenticationError: Invalid API key

​ConnectionTimeout: Request timed out

​SSL Certificate Error

​Enable Debug Logging

​Version Compatibility

​Next Steps