> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation & Setup

> Install and configure the Kubiya Control Plane SDK

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](https://compose.kubiya.ai)

## Installation

### Install via pip

```bash theme={null}
pip install kubiya-sdk
```

### Install from Source

```bash theme={null}
git clone https://github.com/kubiyabot/sdk-py.git
cd sdk-py
pip install -e .
```

### Optional Dependencies

```bash theme={null}
# 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](https://compose.kubiya.ai)
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:

```python theme={null}
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:

```python theme={null}
from kubiya import ControlPlaneClient

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

### Version Check

```python theme={null}
import kubiya
print(f"Kubiya SDK version: {kubiya.__version__}")
```

### Feature Test

```python theme={null}
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`):

```json theme={null}
{
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "python.formatting.provider": "black",
    "python.analysis.typeCheckingMode": "basic"
}
```

3. For better autocompletion, install type stubs:

```bash theme={null}
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:

```bash theme={null}
pip install kubiya-sdk jupyter
jupyter notebook
```

```python theme={null}
# 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`:

```dockerfile theme={null}
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`:

```yaml theme={null}
version: '3.8'

services:
  kubiya-app:
    build: .
    environment:
      - KUBIYA_API_KEY=${KUBIYA_API_KEY}
    volumes:
      - ./app:/app
    command: python main.py
```

Run with:

```bash theme={null}
docker-compose up
```

### Environment Variables

Configure your environment by creating a `.env` file:

```bash theme={null}
# Kubiya API Key (Required)
KUBIYA_API_KEY=your-kubiya-api-key
```

## Development Setup

For SDK development and contributions:

### Clone Repository

```bash theme={null}
git clone https://github.com/kubiyabot/sdk-py.git
cd sdk-py
```

### Create Virtual Environment

```bash theme={null}
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

### Install Development Dependencies

```bash theme={null}
pip install -e ".[dev]"
```

### Run Tests

```bash theme={null}
# 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

```bash theme={null}
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

```python theme={null}
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

```python theme={null}
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)

```python theme={null}
import ssl
ssl._create_default_https_context = ssl._create_unverified_context
```

### Enable Debug Logging

For troubleshooting, enable debug logging:

```python theme={null}
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:

<CardGroup cols={2}>
  <Card title="Quick Start Guide" icon="rocket" href="/sdk/quick-start">
    Build your first integration in minutes
  </Card>

  <Card title="Control Plane Client" icon="network-wired" href="/sdk/control-plane-client-overview">
    Learn the Control Plane client services
  </Card>

  <Card title="Context Graph" icon="project-diagram" href="/sdk/context-graph">
    Query entities and relationships
  </Card>

  <Card title="Examples" icon="lightbulb" href="/sdk/examples">
    Explore real-world usage patterns
  </Card>
</CardGroup>