Installation & Setup

Install and configure the Kubiya Python SDK

Get the Kubiya Python SDK installed and configured in your environment.

Prerequisites

Before installing the SDK, ensure you have:

• Python 3.8+ installed on your system
• pip package manager
• Kubiya API Key from the Kubiya platform

Installation

Install via pip

The simplest way to install the SDK is via pip:

pip install kubiya-sdk

Install from Source

For the latest development version:

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

Install with Optional Dependencies

# 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

Option 1: Environment Variables (Recommended)

Set your API key as an environment variable:

export KUBIYA_API_KEY="your-api-key-here"

For persistence, add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

# Add to ~/.zshrc or ~/.bashrc
export KUBIYA_API_KEY="your-api-key-here"
export KUBIYA_BASE_URL="https://api.kubiya.ai"  # Optional

####Option 2: Configuration File

Create a configuration file at ~/.kubiya/config.yaml:

api_key: your-api-key-here
base_url: https://api.kubiya.ai
timeout: 30
retry_attempts: 3

Option 3: Programmatic Configuration

Configure directly in your Python code:

from kubiya import KubiyaClient

client = KubiyaClient(
    api_key="your-api-key",
    base_url="https://api.kubiya.ai",
    timeout=60,
    retry_attempts=3
)

Verify Installation

Quick Test

Test your installation and connection:

from kubiya import KubiyaClient

# Initialize client
client = KubiyaClient()

try:
    # Test connection
    print("✅ SDK installed successfully!")
    print(f"Connected to: {client.base_url}")
except Exception as e:
    print(f"❌ Connection failed: {e}")

Version Check

Check your installed SDK version:

import kubiya

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

Feature Test

Test DSL functionality:

from kubiya.dsl import workflow

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

print("✅ Workflow DSL working!")
print(wf.to_dict())

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"]
}

3. 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 KubiyaClient, workflow

client = KubiyaClient()

# Define and execute workflows interactively
wf = workflow("notebook-workflow").step("test", "echo 'Running in Jupyter!'")

Docker Setup

Using Docker

Create a Dockerfile:

FROM python:3.11-slim

# Install Kubiya SDK
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"]

Build and run:

docker build -t my-kubiya-app .
docker run -e KUBIYA_API_KEY=your-key my-kubiya-app

Docker Compose

Create a docker-compose.yml:

version: '3.8'
services:
  kubiya-workflows:
    build: .
    environment:
      - KUBIYA_API_KEY=${KUBIYA_API_KEY}
      - KUBIYA_BASE_URL=https://api.kubiya.ai
    volumes:
      - ./workflows:/app/workflows
    command: python workflows/main.py

Run with:

docker-compose up

Development Setup

For SDK development and contributions:

Clone Repository

git clone https://github.com/kubiyabot/workflow_sdk.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

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

client = KubiyaClient(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 KubiyaClient
client = KubiyaClient(debug=True)

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 workflow in 5 minutes

Client SDK Overview

Learn how to interact with Kubiya APIs

Workflow DSL

Define workflows as code with Python

Examples

Explore real-world usage patterns