# Quick Start

**Get started with DevOps AI Toolkit in minutes — deploy applications, manage policies, and remediate issues using AI-powered Kubernetes workflows.**

> **For the easiest setup**, we recommend installing the complete dot-ai stack which includes all components pre-configured. See the [Stack Installation Guide](/docs/stack).
>
> Continue below if you want to install components individually (for non-Kubernetes setups or granular control over configuration).

## Overview

**What it does**: DevOps AI Toolkit provides AI-powered Kubernetes deployment, remediation, policy management, and capability discovery through conversational workflows via [MCP](/docs/mcp) or the [CLI](/docs/cli).

**Use when**: You want intelligent Kubernetes operations without memorizing commands, need AI-powered troubleshooting, or want to establish governance policies across your cluster.

**📖 Full Guide**: See the [Deployment Guide](setup/deployment.md) for detailed configuration options and the [Tools Overview](tools/overview.md) for complete feature reference.

## Prerequisites

**Works without AI keys:**
- ✅ **Shared prompts library** - No API key needed, works with any MCP-enabled coding agent

**For AI-powered features (deployment, remediation, patterns, policies, capabilities):**
- **AI Model API key** - Required for AI analysis and intelligent recommendations
  - **Multiple AI models supported** - see [AI Model Configuration](setup/deployment.md#ai-model-configuration) for all options and setup
  - **Quick setup**: Claude (default) - `export ANTHROPIC_API_KEY=your_key_here`

**For Kubernetes deployment recommendations:**
- **kubectl** configured with cluster access
  - Verify cluster access with: `kubectl get nodes`
  - Should show your cluster nodes without authentication errors

**For organizational pattern management:**
- **Vector DB service** (Qdrant) for pattern storage and semantic search
- **Embeddings** - Required for semantic pattern matching (in this guide, enabled via `localEmbeddings.enabled=true`; alternatively use a cloud provider — see [Embedding Provider Configuration](setup/deployment.md#embedding-provider-configuration))

**For policy management and governance:**
- **Vector DB service** (Qdrant) for policy storage and semantic search
- **Embeddings** - Required for semantic policy matching (same configuration as above)
- **Optional**: Kyverno installed in cluster for active policy enforcement

## Installation

DevOps AI Toolkit runs as a server on Kubernetes. AI agents connect to it via [MCP](/docs/mcp) or the [CLI](/docs/cli). This guide walks through server deployment and MCP client setup.

## Usage

**🎯 Recommended: Kubernetes Setup (Full Features)**
Production-ready deployment with autonomous capability scanning via controller:

### Step 0: Create a Kubernetes Cluster (Optional)

Skip this step if you already have a Kubernetes cluster with an ingress controller.

**Prerequisites:** [Install Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) if you don't have it.

**Create a Kind cluster with ingress support:**
```bash
# Create Kind cluster configuration
cat > kind-config.yaml << 'EOF'
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 80
    hostPort: 80
    protocol: TCP
  - containerPort: 443
    hostPort: 443
    protocol: TCP
EOF

# Create the cluster
kind create cluster --name dot-ai --config kind-config.yaml

# Install nginx ingress controller for Kind
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml

# Wait for ingress controller to be ready
kubectl wait --namespace ingress-nginx \
  --for=condition=ready pod \
  --selector=app.kubernetes.io/component=controller \
  --timeout=90s
```

### Step 1: Set Environment Variables
```bash
export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"

# Required — static token for REST API, CI/CD, and MCP clients without OAuth
export DOT_AI_AUTH_TOKEN=$(openssl rand -base64 32)

# Ingress class - change to match your ingress controller (traefik, haproxy, etc.)
export INGRESS_CLASS_NAME="nginx"
```

### Step 2: Install via Helm
```bash
# Set versions from GitHub packages
export DOT_AI_VERSION="..."  # https://github.com/vfarcic/dot-ai/pkgs/container/dot-ai%2Fcharts%2Fdot-ai
export DOT_AI_CONTROLLER_VERSION="..."  # https://github.com/vfarcic/dot-ai-controller/pkgs/container/dot-ai-controller%2Fcharts%2Fdot-ai-controller

# Install controller (enables autonomous capability scanning)
helm install dot-ai-controller \
  oci://ghcr.io/vfarcic/dot-ai-controller/charts/dot-ai-controller:$DOT_AI_CONTROLLER_VERSION \
  --namespace dot-ai --create-namespace --wait

# Install MCP server
helm install dot-ai-mcp oci://ghcr.io/vfarcic/dot-ai/charts/dot-ai:$DOT_AI_VERSION \
  --set secrets.anthropic.apiKey="$ANTHROPIC_API_KEY" \
  --set secrets.auth.token="$DOT_AI_AUTH_TOKEN" \
  --set localEmbeddings.enabled=true \
  --set ingress.enabled=true \
  --set ingress.className="$INGRESS_CLASS_NAME" \
  --set ingress.host="dot-ai.127.0.0.1.nip.io" \
  --set controller.enabled=true \
  --namespace dot-ai --wait
```

### Step 3: Create MCP Configuration

Create the MCP client configuration file with your auth token:

```bash
cat > .mcp.json << EOF
{
  "mcpServers": {
    "dot-ai": {
      "type": "http",
      "url": "http://dot-ai.127.0.0.1.nip.io",
      "headers": {
        "Authorization": "Bearer $DOT_AI_AUTH_TOKEN"
      }
    }
  }
}
EOF
```

**Notes:**
- The `$DOT_AI_AUTH_TOKEN` variable is expanded when creating the file. Make sure you're in the same terminal session where you set the environment variables in Step 1.
- **OAuth is enabled by default.** MCP clients with OAuth support (Claude Code, Codex, Windsurf) can authenticate via browser instead of using the static token — see [Authentication](setup/authentication.md) for details.

### Step 4: Start Your MCP Client

```bash
claude  # or your preferred MCP-enabled AI tool
```

Verify everything works by asking:
```
Show dot-ai status
```

You should see a status report showing all components are healthy.

**What you get:**
- ✅ **Full Features**: All capabilities including autonomous scanning via controller
- ✅ **Production-Ready**: Scalable deployment with proper resource management
- ✅ **Automatic Capability Discovery**: Controller watches for CRD changes and scans automatically
- ✅ **Team Collaboration**: Shared MCP server accessible by multiple developers

**Full Configuration**: See the [Deployment Guide](setup/deployment.md) for advanced configuration options and the [Authentication Guide](setup/authentication.md) for OAuth setup and user management.

### Step 5: Start Using Conversational Workflows

Try these example prompts to explore the toolkit:

| What You Want | Example Prompt | Guide |
|---------------|----------------|-------|
| Scan capabilities | Use controller (recommended) or "Scan my cluster for capabilities" | [Capability Management](tools/capability-management.md) |
| Query cluster | "What databases are running?" | [Cluster Query](tools/query.md) |
| Deploy an app | "I want to deploy a web application" | [Recommendation Guide](tools/recommend.md) |
| Operate resources | "Scale my database to 3 replicas" | [Operations Guide](tools/operate.md) |
| Fix issues | "Something is wrong with my database" | [Remediation Guide](tools/remediate.md) |
| Create patterns | "Create a pattern for database deployments" | [Pattern Management](organizational-data/patterns.md) |
| Create policies | "Create a policy requiring resource limits" | [Policy Management](organizational-data/policies.md) |
| Setup project | "Help me setup governance files" | [Project Setup Guide](tools/project-setup.md) |
| Use prompts | `/dot-ai:prd-create` | [Prompts Guide](tools/prompts.md) |

## Next Steps

📖 **[Deployment Guide →](setup/deployment.md)** - Detailed configuration, troubleshooting, and examples

📖 **[Complete Tools & Features Reference →](tools/overview.md)** - Comprehensive guide to all available tools, workflows, and advanced features