Testkube AI Configuration Reference

This document provides a comprehensive reference for enabling and configuring Testkube AI functionality, including the AI Assistant, AI Agents, AI Agent Triggers, and related features.

Cloud Control Plane Users

For users of the Testkube Cloud Control Plane, enabling AI functionality is straightforward:

Enable AI Assistant

The Testkube AI Assistant is disabled by default for new organizations.

Who can enable: Organization Owner or Admin

How to enable:

1. Via the Initial AI Assistant Prompt: When you first access the AI Assistant, an initial prompt is displayed with action buttons that allow you to either enable the feature or keep it disabled.

2. Through Organization Settings: Navigate to Organization Settings → Product Features tab and toggle AI Assistant on.

Once enabled, the AI Assistant, AI Agents, and AI Agent Triggers will be available in your Testkube Dashboard.

Custom Models

In addition to the platform default model, you can add your own models directly from the Dashboard to make additional models available for AI Chats. See Configuring AI Models for details.

Default LLM and Model

The default LLM used by AI functionality is OpenAI's GPT-5.2-Codex.

For Cloud installations, the platform default model is managed by Testkube. You can add additional models via Custom Models in the Dashboard.

For On-Prem installations, you can configure your own OpenAI API Key or use a different LLM/model as described in the On-Prem Users section below.

---

On-Prem Users

Self-hosted installations require additional infrastructure and configuration apart from the above Cloud Control Plane configuration.

PostgreSQL

The AI service uses PostgreSQL for conversation persistence. It shares the control plane's PostgreSQL instance by default — no additional database setup is required.

Helm Configuration

Configure the following components in your testkube-enterprise Helm values:

testkube-ai-service:
  enabled: true  # Default: false
  inference:
    defaults:
      secretRef: "<secret-name>"      # K8s secret storing the API key
      secretRefKey: "api-key"         # Key within the secret
    agent:
      - model: gpt-4o
        default: true
    tasks:
      model: gpt-4o-mini
    embeddings:
      model: text-embedding-3-small

# Enable AI features in the UI
testkube-cloud-ui:
  ai:
    enabled: true  # Default: false
    aiServiceApiUri: "https://ai.<your-domain>"

LLM API Key Setup

Create a Kubernetes secret containing your LLM API key:

kubectl -n <namespace> create secret generic <secret-name> \
  --from-literal=api-key=<your-api-key>

tip

The secret must be in the same namespace as the Testkube control plane.

The inference: Configuration Block

The inference: block is the recommended way to configure LLM models for the AI service. It uses role-based keys to describe what each model is used for:

Role	Type	Purpose
agent	Array	Reasoning models for AI Agents — user-selectable in the Copilot UI
tasks	Object (optional)	Lightweight model for title generation, classification. Falls back to default agent model if omitted
embeddings	Object (optional)	Embeddings model for vector search. Omit to disable embeddings entirely

Shared Defaults

The defaults section provides shared values inherited by all models unless overridden at the model level:

Field	Description
url	Base URL for LLM API (e.g., https://proxy.internal/v1). Defaults to OpenAI if omitted
apiKey	API key (plain text — prefer secretRef for production)
secretRef	K8s secret name
secretRefKey	Key within the secret
extraHeaders	Extra HTTP headers merged into all requests
queryParams	Query parameters appended to all request URLs

Model Properties

Each model entry (agent, tasks, embeddings) supports these fields in addition to inheriting from defaults:

Field	Description
model	Model identifier sent in the API request body (e.g., gpt-4o)
url	Custom endpoint URL (overrides defaults.url)
apiKey	API key for this model (overrides defaults.apiKey)
secretRef	K8s secret name (overrides defaults.secretRef)
secretRefKey	Key within the secret (overrides defaults.secretRefKey)
extraHeaders	Extra HTTP headers (replaces defaults.extraHeaders if set)
queryParams	Query parameters (replaces defaults.queryParams if set)
temperature	Temperature setting — agent and tasks only
label	Human-readable name for the UI dropdown — agent only
default	Mark which agent model is the default — agent only

Override Semantics

Per-model extraHeaders and queryParams replace the defaults entirely (not merged key-by-key). If you need both default and model-specific headers, repeat the shared ones in the per-model block.

LLM Provider Examples

OpenAI (Direct)

inference:
  defaults:
    secretRef: "openai-secret"
    secretRefKey: "api-key"
  agent:
    - model: gpt-4o
      default: true
  tasks:
    model: gpt-4o-mini
  embeddings:
    model: text-embedding-3-small

Azure OpenAI — Separate Deployments

Azure OpenAI uses per-deployment URLs, header-based auth, and requires an api-version query parameter:

inference:
  defaults:
    extraHeaders:
      api-key: "azure-shared-key"
    queryParams:
      api-version: "2024-02-01"
  agent:
    - model: gpt-4o
      default: true
      url: "https://myresource.openai.azure.com/openai/deployments/gpt-4o"
  tasks:
    model: gpt-4o-mini
    url: "https://myresource.openai.azure.com/openai/deployments/gpt-4o-mini"
  embeddings:
    model: text-embedding-3-small
    url: "https://myresource.openai.azure.com/openai/deployments/text-embedding-3-small"

vLLM / Local Deployment — No Embeddings

When your LLM provider doesn't support the /v1/embeddings endpoint, omit the embeddings block to disable it:

inference:
  defaults:
    url: "http://vllm.internal:8000/v1"
  agent:
    - model: meta-llama/Llama-3.1-70B
      default: true
      temperature: 0
  tasks:
    model: meta-llama/Llama-3.1-8B
  # embeddings: omitted — embeddings features disabled

LiteLLM Proxy — Multiple Models

inference:
  defaults:
    url: "https://litellm.corp.internal/v1"
    apiKey: "proxy-master-key"
  agent:
    - model: openai/gpt-4o
      default: true
    - model: anthropic/claude-sonnet-4-20250514
  tasks:
    model: openai/gpt-4o-mini
  embeddings:
    model: openai/text-embedding-3-small

Mixed Providers — Different Keys and Endpoints Per Role

inference:
  agent:
    - model: claude-sonnet-4-20250514
      default: true
      url: "https://api.anthropic.com/v1"
      extraHeaders:
        x-api-key: "sk-ant-..."
        anthropic-version: "2023-06-01"
    - model: gpt-4o
      url: "https://api.openai.com/v1"
      apiKey: "sk-proj-..."
  tasks:
    model: gpt-4o-mini
    url: "https://api.openai.com/v1"
    apiKey: "sk-proj-..."
  embeddings:
    model: text-embedding-3-small
    url: "https://api.openai.com/v1"
    apiKey: "sk-proj-..."

K8s Secrets for API Keys

inference:
  defaults:
    url: "https://api.openai.com/v1"
    secretRef: "ai-service-llm-keys"
    secretRefKey: "openai-api-key"
  agent:
    - model: gpt-4o
      default: true
  tasks:
    model: gpt-4o-mini
  embeddings:
    model: text-embedding-3-small
    secretRef: "ai-service-embeddings-key"
    secretRefKey: "api-key"

Testkube Hosted LLM Proxy (Trials Only)

testkube-ai-service:
  enabled: true
  inference:
    defaults:
      url: "https://llm.testkube.io"
    agent:
      - model: gpt-4o
        default: true

warning

The hosted proxy is intended only for trials, demos, and onboarding. It has usage limits and is not recommended for production workloads.

Disabling Embeddings

To disable embeddings (e.g., when your LLM provider doesn't support /v1/embeddings), simply omit the embeddings block from your inference: configuration. The AI service will skip vector store initialization and work without embedding-enhanced context.

Authentication Configuration

The AI service requires OAuth/OIDC authentication. Configure one of the following:

Option	Environment Variable	Description
OIDC Discovery (recommended)	OIDC_CONFIGURATION_URL	Auto-discovers endpoints from Dex
Manual configuration	OAUTH_JWKS_URL + OAUTH_ISSUER	Provide both URLs manually

When using Dex (default), authentication is automatically configured via the global Dex issuer settings.

Network Requirements

Ensure your firewall allows traffic to:

• LLM endpoint — OpenAI API or your custom LLM service
• Testkube AI Service API — The deployed AI service endpoint

For corporate proxies, inject proxy variables into the AI service pod:

testkube-ai-service:
  enabled: true
  inference:
    defaults:
      secretRef: "<secret-name>"
  extraEnvVars:
    - name: HTTP_PROXY
      value: "http://proxy.domain:8080"
    - name: HTTPS_PROXY
      value: "https://proxy.domain:8043"
    - name: NO_PROXY
      value: ""

---

Legacy Configuration (Deprecated)

caution

The llmApi, model, models[], and modelsFile keys are deprecated and will be removed in a future release. Please migrate to the inference: block above. Existing deployments using these keys will continue to work — the system automatically maps them to the new format internally.

Legacy configuration reference (click to expand)

Legacy Simple Configuration

testkube-ai-service:
  enabled: true
  llmApi:
    secretRef: "<secret-name>"

Legacy Models Array

testkube-ai-service:
  enabled: true
  models:
    - name: gpt-5.2-codex
      type: primary
      temperature: 0
    - name: gpt-5-mini
      type: lightweight
  llmApi:
    secretRef: "llm-secrets"

Legacy Model Types

Type	New Equivalent	Purpose
primary	agent	Main reasoning models
lightweight	tasks	Quick UI enrichment tasks

Legacy Configuration Priority

1. modelsFile — External YAML file
2. models — Array of model configurations
3. model — Simple single model name

Legacy Environment Variables

Variable	New Equivalent	Description
LLM_API_KEY	INFERENCE_DEFAULT_API_KEY	API key for LLM service
LLM_API_URL	inference.defaults.url	Custom LLM endpoint
MODEL_NAME	inference.agent[0].model	Model name
AI_MODELS_FILE	INFERENCE_CONFIG_FILE	Path to model config file (different YAML schema — not a direct drop-in replacement)
LLM_EXTRA_HEADERS	inference.defaults.extraHeaders	Extra HTTP headers

---

Security & Compliance

Data Privacy

Where your data is processed depends on your LLM configuration:

Configuration	Data Residency
Self-hosted LLM	Data never leaves your infrastructure. Supports air-gapped deployments and full compliance with data residency requirements.
Third-party provider (your API key)	Queries and Testkube context (logs, workflow names, execution details) are sent to the provider's API. Review their data handling policies.
Testkube hosted proxy	For trials/demos only. Do not use for production or sensitive environments.

Disabling Telemetry

To disable diagnostic telemetry collection:

testkube-ai-service:
  enabled: true
  extraEnvVars:
    - name: DO_NOT_TRACK
      value: "true"

See Telemetry Configuration for more details.

Air-Gapped Environments

AI functionality supports fully disconnected deployments when using self-hosted LLM infrastructure. See Repackaging Testkube for air-gapped setup guidance.

---

Feature Flags Reference

Flag/Setting	Location	Default	Purpose
testkube-ai-service.enabled	Helm	false	Deploy AI service
testkube-cloud-ui.ai.enabled	Helm	false	Enable UI AI features
MCP_ENABLED	Control Plane env	false	Enable MCP integration
AI_SERVICE_URL	Control Plane env	""	AI service URL — required for AI Agent Triggers and session execution
aiCopilotEnabled	User settings (API)	false	Per-user AI toggle

---

Environment Variables Reference

The following environment variables can be configured for the AI service:

Required Variables

Variable	Description
CONTROL_PLANE_ENDPOINT	URL endpoint for the Testkube Control Plane
POSTGRES_URI	PostgreSQL connection string for LangGraph checkpointing

Control Plane Variables

These are set on the Control Plane (cloud-api), not the AI service:

Variable	Required	Description
AI_SERVICE_URL	Yes (for AI features)	Base URL of the AI service (e.g. http://testkube-enterprise-ai-service:9090). Required for AI Agent sessions and triggers.
API_BASE_URL	Yes (for AI features)	External base URL of the cloud-api used by the AI service for callbacks (e.g. https://api.example.com)
MCP_ENABLED	No	Set to true to enable MCP integration (default: false)

Inference Configuration

Variable	Description
INFERENCE_CONFIG_FILE	Path to the inference configuration YAML file (set automatically by Helm)
INFERENCE_DEFAULT_API_KEY	Default API key for inference (from inference.defaults.secretRef)

Authentication

Variable	Required	Description
OIDC_CONFIGURATION_URL	Conditional	OIDC discovery URL (recommended)
OAUTH_JWKS_URL	Conditional	JWK set document URL (if not using OIDC discovery)
OAUTH_ISSUER	Conditional	OAuth issuer URL (if not using OIDC discovery)

---

Quick Start Checklist

Cloud Users

• Enable AI Assistant in Organization Settings → Product Features

On-Prem Users

• PostgreSQL database available and accessible
• LLM API key secret created in the correct namespace
• Helm values configured:
  • testkube-ai-service.enabled: true
  • testkube-ai-service.inference.defaults.secretRef set
  • testkube-ai-service.inference.agent configured with at least one model
  • testkube-cloud-ui.ai.enabled: true
  • testkube-cloud-ui.ai.aiServiceApiUri set
• Control Plane environment variables set:
  • AI_SERVICE_URL pointing to the AI service (required for sessions and triggers)
  • API_BASE_URL pointing to the external cloud-api URL
  • MCP_ENABLED=true if using MCP integration
• Network access to LLM endpoint configured
• OAuth/OIDC authentication configured (or using default Dex)
• Enable AI Assistant in Organization Settings after deployment

---

External Secrets

If using External Secrets Operator:

testkube-ai-service:
  externalSecrets:
    enabled: true
    refreshInterval: 5m
    clusterSecretStoreName: secret-store

---

Related Documentation

• Testkube AI Overview — High-level overview of all AI capabilities
• AI Assistant — Using the AI Assistant in the Dashboard
• AI Agents — Creating and managing AI Agents
• AI Agent Triggers — Automating agent execution on workflow events
• Configuring AI Models — Adding custom models from the Dashboard
• AI Architecture — How Testkube AI components work together