Skip to main content
Install and configure the Control Plane SDK (for agents, integrations, secrets) and the Workflow DSL (for defining and executing workflows).

​
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 workflow_sdk
pip install -e .

​
Optional Dependencies (Workflow DSL)

# For async support
pip install kubiya-sdk[async]

# 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 (Control Plane)

PowerShell (Windows): 
$env:KUBIYA_API_KEY = "your-api-key-here"
$env:KUBIYA_CONTROL_PLANE_BASE_URL = "https://control-plane.kubiya.ai"  # or on-prem URL
macOS/Linux shells: 
export KUBIYA_API_KEY="your-api-key-here"
export KUBIYA_CONTROL_PLANE_BASE_URL="https://control-plane.kubiya.ai"

​
Option 2: Programmatic Configuration (Control Plane)

Configure directly in your Python code: 
from kubiya_control_plane import ControlPlaneClient

client = ControlPlaneClient(
  api_key="your-api-key",
  base_url="https://control-plane.kubiya.ai"
)

​
Verify Installation

​
Control Plane: Quick Test

Test your installation and connection: 
from kubiya_control_plane import ControlPlaneClient

client = ControlPlaneClient()
status = client.health.check()
print(status)

​
Version Check (Workflow DSL)

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

​
Workflow DSL: Feature Test

from kubiya.dsl import workflow

wf = (
  workflow("test-workflow")
    .description("Test workflow")
    .step("hello", "echo 'Hello from Kubiya!'")
)

for event in client.execute_workflow(wf.to_dict(), stream=True):
  print(event)

​
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",
    "python.analysis.extraPaths": ["./kubiya"]
}
  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 workflow
from kubiya_control_plane import ControlPlaneClient

client = ControlPlaneClient()
wf = workflow("notebook-workflow").step("test", "echo 'Running in Jupyter!'")
for event in client.execute_workflow(wf.to_dict(), stream=True):
  print(event)

​
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 workflow code
COPY workflows/ /app/workflows/
WORKDIR /app

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

​
Docker Compose

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

services:
  kubiya-app:
    build: .
    environment:
      - KUBIYA_API_KEY=${KUBIYA_API_KEY}
    volumes:
      - ./workflows:/app/workflows
    command: python workflows/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 (Workflow DSL)

For SDK development and contributions:

​
Clone Repository

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

​
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)
export KUBIYA_API_KEY=your-key
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 (Control Plane)

Solution: Verify your API key is correct 
echo $KUBIYA_API_KEY
# Update if needed
export KUBIYA_API_KEY="your-correct-key"

​
ConnectionTimeout: Request timed out

Solution: Increase timeout or check network connectivity 
from kubiya_control_plane import ControlPlaneClient
client = ControlPlaneClient()

​
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 (Workflow DSL)

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

from kubiya import KubiyaClient
client = KubiyaClient(debug=True)

​
Version Compatibility (Workflow DSL)

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 agent and workflow in minutes

Client SDK Overview

Learn the Control Plane client services

Workflow DSL

Define workflows as code with Python

Examples

Explore real-world usage patterns