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:

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.
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.

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-5.2
        default: true
    tasks:
      model: gpt-5-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-5.2`)
`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

For Kubernetes deployment examples and verification commands, see Alternative Model Providers.

OpenAI (Direct)

inference:
  defaults:
    secretRef: "openai-secret"
    secretRefKey: "api-key"
  agent:
    - model: gpt-5.2
      default: true
  tasks:
    model: gpt-5-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-5.2
      default: true
      url: "https://myresource.openai.azure.com/openai/deployments/gpt-5.2"
  tasks:
    model: gpt-5-mini
    url: "https://myresource.openai.azure.com/openai/deployments/gpt-5-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"
    secretRef: "proxy-auth"
    secretRefKey: "api-key"
  agent:
    - model: openai/gpt-5.2
      default: true
    - model: claude-sonnet-5
  tasks:
    model: openai/gpt-5-mini
  embeddings:
    model: openai/text-embedding-3-small

The model names above must match the proxy's configured model_name aliases; provider prefixes are not automatically exposed.

Mixed Providers — Different Keys and Endpoints Per Role

Claude uses LiteLLM to translate the OpenAI-compatible requests to Anthropic's API; setting Anthropic headers on its native endpoint does not perform that translation.

inference:
  agent:
    - model: claude-sonnet-5
      default: true
      url: "https://litellm.corp.internal/v1"
      secretRef: "proxy-auth"
      secretRefKey: "api-key"
    - model: gpt-5.2
      url: "https://api.openai.com/v1"
      apiKey: "sk-proj-..."
  tasks:
    model: gpt-5-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-5.2
      default: true
  tasks:
    model: gpt-5-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-5.2
        default: true
    tasks:
      model: gpt-5-mini

The hosted proxy serves a fixed set of models chosen by Testkube — you cannot add to it:

Chat: gpt-5.2 and gpt-5-mini
Embeddings: text-embedding-ada-002

Any other model name returns an invalid-model error from the proxy. This includes gpt-4o and gpt-4o-mini, which the hosted proxy no longer serves — move any configuration still naming them to gpt-5.2 / gpt-5-mini.

warning

The hosted proxy requires an active trial license, and this is enforced. When a license converts to a commercial plan or passes its expiry date, the proxy stops serving it and the AI service falls back to whatever model credentials you have configured. Set up your own provider before a trial ends, otherwise AI features stop working.

License changes take up to an hour to take effect, in both directions, so access can briefly outlast a converted license or lag behind a renewal.

The proxy also 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
      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

modelsFile — External YAML file
models — Array of model configurations
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

External Secrets

If using External Secrets Operator:

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

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

Cloud Control Plane Users​

Enable AI Assistant​

Custom Models​

Default LLM and Model​

On-Prem Users​

Helm Configuration​

LLM API Key Setup​

The inference: Configuration Block​

Shared Defaults​

Model Properties​

LLM Provider Examples​

OpenAI (Direct)​

Azure OpenAI — Separate Deployments​

vLLM / Local Deployment — No Embeddings​

LiteLLM Proxy — Multiple Models​

Mixed Providers — Different Keys and Endpoints Per Role​

K8s Secrets for API Keys​

Testkube Hosted LLM Proxy (Trials Only)​

Disabling Embeddings​

Authentication Configuration​

Network Requirements​

Legacy Configuration (Deprecated)​

Legacy Simple Configuration​

Legacy Models Array​

Legacy Model Types​

Legacy Configuration Priority​

Legacy Environment Variables​

Security & Compliance​

Data Privacy​

Disabling Telemetry​

Air-Gapped Environments​

Feature Flags Reference​

Environment Variables Reference​

Required Variables​

Control Plane Variables​

Inference Configuration​

Authentication​

Quick Start Checklist​

Cloud Users​

On-Prem Users​

External Secrets​

Related Documentation​

Cloud Control Plane Users

Enable AI Assistant

Custom Models

Default LLM and Model

On-Prem Users

Helm Configuration

LLM API Key Setup

The `inference:` Configuration Block

Shared Defaults

Model Properties

LLM Provider Examples

OpenAI (Direct)

Azure OpenAI — Separate Deployments

vLLM / Local Deployment — No Embeddings

LiteLLM Proxy — Multiple Models

Mixed Providers — Different Keys and Endpoints Per Role

K8s Secrets for API Keys

Testkube Hosted LLM Proxy (Trials Only)

Disabling Embeddings

Authentication Configuration

Network Requirements

Legacy Configuration (Deprecated)

Legacy Simple Configuration

Legacy Models Array

Legacy Model Types

Legacy Configuration Priority

Legacy Environment Variables

Security & Compliance

Data Privacy

Disabling Telemetry

Air-Gapped Environments

Feature Flags Reference

Environment Variables Reference

Required Variables

Control Plane Variables

Inference Configuration

Authentication

Quick Start Checklist

Cloud Users

On-Prem Users

External Secrets

Related Documentation