Installation

Install and configure the Kubiya Workflow SDK

Installation

Get started with the Kubiya Workflow SDK in minutes. This guide covers installation, configuration, and basic usage.

Requirements

• Python 3.8 or higher
• pip package manager
• Kubiya API key (get one at app.kubiya.ai)

Install via pip

Latest Stable

pip install kubiya-workflow-sdk

pip install kubiya-workflow-sdk

pip install git+https://github.com/kubiyabot/workflow_sdk.git

pip install kubiya-workflow-sdk==0.0.5

Verify Installation

python -c "import kubiya_workflow_sdk; print(kubiya_workflow_sdk.__version__)"

Set up Authentication

Set your API key as an environment variable:

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

Or create a .env file in your project:

KUBIYA_API_KEY=your-api-key-here
KUBIYA_API_URL=https://api.kubiya.ai  # Optional, defaults to production

Optional Dependencies

For AI Providers

# For ADK provider
pip install kubiya-workflow-sdk[adk]

# For FastMCP provider
pip install kubiya-workflow-sdk[mcp]

# All providers
pip install kubiya-workflow-sdk[all]

For Development

# Install with development dependencies
pip install kubiya-workflow-sdk[dev]

Docker Installation

If you prefer using Docker:

FROM python:3.11-slim

WORKDIR /app

# Install SDK
RUN pip install kubiya-workflow-sdk

# Copy your workflow files
COPY . .

# Run your workflow
CMD ["python", "workflow.py"]

SDK Capabilities

The Kubiya SDK provides comprehensive tools for workflow automation:

Core Features

1. Workflow Definition

   Create workflows using Python DSL or YAML

   from kubiya import workflow, step
   
   @workflow
   def my_automation():
       step.shell("echo 'Hello Kubiya!'")
   

2. AI Generation

   Generate workflows from natural language

   from kubiya_workflow_sdk import KubiyaWorkflow
   
   workflow = KubiyaWorkflow.from_prompt(
       "Deploy my Node.js app to Kubernetes"
   )
   

3. Container Orchestration

   Run any Docker container as a workflow step

   step.container(
       image="tensorflow/tensorflow:latest",
       command="python train_model.py"
   )
   

Client Configuration

Basic Setup

from kubiya_workflow_sdk import Client

# Initialize with API key
client = Client(
    api_key="your-api-key",
    api_url="https://api.kubiya.ai"  # Optional, defaults to production
)

Advanced Configuration

from kubiya_workflow_sdk import Client, Config

# Detailed configuration
config = Config(
    api_key="your-api-key",
    api_url="https://api.kubiya.ai",
    timeout=30,  # Request timeout in seconds
    retry_count=3,  # Number of retries
    retry_delay=1.0,  # Delay between retries
    verify_ssl=True,  # SSL verification
    proxy=None,  # HTTP proxy if needed
)

client = Client(config=config)

Environment Variables

Set environment variables for automatic configuration:

export KUBIYA_API_KEY="your-api-key"
export KUBIYA_API_URL="https://api.kubiya.ai"
export KUBIYA_TIMEOUT="30"
export KUBIYA_RETRY_COUNT="3"

Then initialize without parameters:

client = Client()  # Reads from environment

SDK Components

1. Workflow Management

from kubiya_workflow_sdk import Workflow, Step

# Object-oriented approach
workflow = Workflow(
    name="data-pipeline",
    description="Process daily data",
    steps=[
        Step(name="fetch", image="alpine", command="wget data.csv"),
        Step(name="process", image="python:3.11", script="process.py")
    ]
)

# Execute
result = client.execute_workflow(workflow)

2. DSL (Domain Specific Language)

from kubiya_workflow_sdk.dsl import workflow

# Fluent interface
wf = (
    workflow("deployment-pipeline")
    .description("Deploy application")
    .step("test", "npm test", image="node:18")
    .step("build", "npm run build")
    .step("deploy", "kubectl apply -f k8s/")
    .build()
)

3. AI Providers

from kubiya_workflow_sdk.providers import get_provider

# ADK provider for AI generation
adk = get_provider("adk", api_key="...")

# Generate workflow
result = await adk.compose(
    task="Create a CI/CD pipeline for Python app",
    mode="act"  # or "plan" for preview
)

4. Streaming Execution

# Real-time execution updates
for event in client.execute_workflow(workflow, stream=True):
    print(f"{event.type}: {event.data}")

5. MCP Server

from kubiya_workflow_sdk.mcp import MCPServer

# Create MCP-compatible server
server = MCPServer(
    name="my-workflows",
    version="1.0.0"
)

# Register workflows as tools
server.register_workflow(workflow)
server.run(port=8080)

Authentication

API Key Authentication

Get your API key from the Kubiya Platform

# Direct API key
client = Client(api_key="key_...")

# From environment
os.environ["KUBIYA_API_KEY"] = "key_..."
client = Client()

# From file
with open(".kubiya-key", "r") as f:
    api_key = f.read().strip()
client = Client(api_key=api_key)

Organization Context

# Specify organization
client = Client(
    api_key="key_...",
    org_name="my-company"  # For multi-org accounts
)

Local Development

Docker Setup

# docker-compose.yml
version: '3.8'
services:
  kubiya-local:
    image: kubiya/sdk:latest
    volumes:
      - .:/workspace
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - KUBIYA_MODE=local

Local Runners

Local runners are created and managed through the Kubiya platform:

1. Via Web Interface: Go to the Kubiya platform and create a new runner
2. Via API: Use the Kubiya API to create a runner programmatically
3. Get Manifest: Receive a Kubernetes manifest or Helm chart
4. Deploy: Apply the manifest to your Kubernetes cluster

# Example: Apply the runner manifest
kubectl apply -f kubiya-runner-manifest.yaml

# Or using Helm
helm install my-runner kubiya/runner -f values.yaml

For detailed setup instructions, see the Runners documentation.

Proxy Configuration

For corporate environments:

# HTTP proxy
client = Client(
    api_key="...",
    proxy="http://proxy.company.com:8080"
)

# SOCKS proxy
client = Client(
    api_key="...",
    proxy="socks5://proxy.company.com:1080"
)

# With authentication
client = Client(
    api_key="...",
    proxy="http://user:[e-mail]:8080"
)

SSL/TLS Configuration

# Disable SSL verification (not recommended)
client = Client(
    api_key="...",
    verify_ssl=False
)

# Custom CA bundle
client = Client(
    api_key="...",
    ca_bundle="/path/to/ca-bundle.crt"
)

SDK Features Matrix

Troubleshooting

Common Issues

ImportError: No module named 'kubiya_workflow_sdk'

# Ensure correct Python environment
which python
pip list | grep kubiya

# Reinstall
pip uninstall kubiya-workflow-sdk
pip install kubiya-workflow-sdk

Authentication Failed

# Check API key format
print(f"Key starts with: {api_key[:7]}")  # Should be "key_..."

# Verify connection
client.test_connection()

SSL Certificate Error

# Temporary workaround
client = Client(verify_ssl=False)

# Permanent fix - update certificates
pip install --upgrade certifi

Docker Permission Denied

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Or use rootless Docker
dockerd-rootless-setuptool.sh install

Version Compatibility

SDK Version	Python	API Version	Features
2.0+	3.8+	v2	AI generation, streaming
1.5+	3.7+	v1	Basic workflows
1.0+	3.6+	v1	Initial release

What’s Next?

Quick Start

Build your first workflow

Workflow Basics

Learn workflow concepts

AI Generation

Generate workflows with AI

API Reference

Explore the full API

Getting Help

Discord

Join our community

GitHub

Report issues

Support

Contact support