This guide walks you through configuring AI providers, selecting a model, and running your first AI Mission in KubeStellar Console. For an overview of what AI Missions can do, see AI Features.
Before setting up AI Missions, ensure you have:
KubeStellar Console running — Follow the Installation guide to deploy the console locally, in Kubernetes, or via Helm.
Kubernetes cluster access — At least cluster configured in your kubeconfig. Verify with:
kubectl config get-contexts
kubectl --context=your-cluster get nodesAn AI provider API key — Obtain a key from or more of these providers:
| Provider | Where to get a key | Documentation |
|---|---|---|
| Anthropic (Claude) | console.anthropic.com/settings/keys | Anthropic API docs |
| OpenAI | platform.openai.com/api-keys | OpenAI API docs |
| Google (Gemini) | aistudio.google.com/apikey | Gemini API docs |
You need provider to get started. You can add additional providers later.
kubestellar-mcp plugins installed — The kubestellar-ops and kubestellar-deploy plugins enable the AI agent to interact with your clusters. See Installation - Step 1 for setup instructions.
The recommended approach for local deployments is to set API keys as environment variables in a .env file.
In the root of your console directory (the same directory as startup-oauth.sh), add or more API keys:
# AI provider keys (at least required for AI features)
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GOOGLE_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Alternative: CLAUDE_API_KEY can also be used for Anthropic
# CLAUDE_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxYou do not need all three providers. Set the keys for the providers you intend to use.
Important: The
.envfile must be in the same directory asstartup-oauth.sh. The startup script loads it from its own directory. Never commit this file to version control — it is already listed in.gitignore.
./startup-oauth.shThe startup script reads the .env file and passes the keys to the backend. If the console is already running, restart it to pick up the new keys.
After the console loads, navigate to Settings (gear icon in the sidebar or /settings). Under the AI & Intelligence section, each configured provider should show a green checkmark indicating a valid key.
Note: The Settings UI for API key configuration is currently limited. For reliable API key setup, use the
.envfile method above. The Settings UI is being improved and will be fully functional in a future release.
You can view the configured providers in the AI & Intelligence section of Settings, though configuration via .env is more reliable.
/settings)..env or system environment variables).Keys set via .env or environment variables persist across browser sessions and take effect immediately (or after restart if using .env).
Note: For Helm or Kubernetes deployments, configure API keys via Kubernetes secrets instead. See Configuration - AI Configuration for Helm values.
Demo mode lets you explore AI Missions without an API key or live cluster connection. It uses pre-recorded responses and synthetic data.
You can also enable demo mode by setting the environment variable:
VITE_DEMO_MODE=true| Aspect | Demo Mode | Live Mode |
|---|---|---|
| Data source | Pre-recorded responses | Real AI provider API calls |
| Cluster interaction | Simulated | Live kubectl commands |
| API key required | No | Yes (at least provider) |
| Token usage | None | Counted against your provider quota |
| Visual indicator | Yellow outline + “Demo” badge on cards | No badge |
| Response variability | Fixed, repeatable | Dynamic, context-aware |
| Repair/Apply actions | Simulated (no real changes) | Real changes to clusters (with approval) |
KubeStellar Console supports multiple AI models across providers. You can switch models at any time.
| Provider | Models | Notes |
|---|---|---|
| Anthropic | Claude Sonnet 4, Claude Opus 4, Claude Haiku 3.5 | Claude Sonnet 4 is the default. Opus 4 provides the highest quality for complex multi-step missions. Haiku 3.5 is faster and cheaper for simple queries. |
| OpenAI | GPT-4o, GPT-4o mini, o3 | GPT-4o is recommended. o3 is best for reasoning-heavy tasks. GPT-4o mini is the most cost-effective. |
| Gemini 2.5 Pro, Gemini 2.5 Flash | Gemini 2.5 Pro handles long context well. Flash is faster and cheaper. |
You can also set the default model via environment variable or Helm values:
# Environment variable
AI_MODEL=claude-sonnet-4-20250514# Helm values
ai:
defaultModel: "claude-sonnet-4-20250514"Click the AI Missions button in the bottom-right corner of the console. The missions panel slides open.
2 steps on how to create a new mission
Click Start Custom Mission to manually create a new mission.
Click Browse Community Missions to use an existing mission created by the community and select a mission type from the panel. The following table describes the supported mission types.
| Mission Type | Use for |
|---|---|
| Troubleshoot | Diagnosing pod crashes, failed deployments, network issues |
| Analyze | Understanding resource usage patterns, security posture, cluster drift |
| Repair | Fixing identified problems with AI-generated patches |
| Upgrade | Planning and executing Kubernetes or application upgrades |
| Deploy | Deploying applications across or more clusters |
Type your question or task in the input field. Be specific about the cluster, namespace, or resource if relevant. Press Cmd+Enter (macOS) or Ctrl+Enter (Linux/Windows) to submit.
The AI reads your cluster state, runs commands, and presents its findings. This may include:
When the AI proposes a change (scaling a deployment, restarting a pod, applying a patch), you see the exact action before it runs. Click Approve to proceed or Reject to skip that step. The AI never makes changes without your explicit approval.
Here are prompts to try for your first missions:
Cluster health check:
Give me a health summary of all my connected clustersTroubleshoot a failing pod:
Why is the pod coredns-abc123 in namespace kube-system crash-looping on cluster prod-east?Analyze resource usage:
Which namespaces on my staging cluster are using the most memory, and are any close to their limits?Deploy an application:
Deploy nginx with 3 replicas to the default namespace on cluster dev-1Security audit:
Check for pods running as root or with privileged security contexts across all clustersCertificate check:
Are any TLS certificates expiring within the next 30 days on my production clusters?Cross-cluster comparison:
Compare the Helm releases installed on cluster staging vs cluster production and show me the differencesSymptoms: No AI Missions button, no “Ask AI” icons on cards, no AI & Intelligence section in Settings.
Causes and solutions:
No API key configured: Add at least provider key via .env or Settings UI (see sections above). Restart the console if using .env.
kubestellar-mcp plugins not installed: The AI agent requires kubestellar-ops and kubestellar-deploy. Verify installation:
which kubestellar-ops kubestellar-deployIf missing, follow Installation - Step 1.
AI mode set to Off: Navigate to Settings > AI & Intelligence and confirm AI Mode is set to Low, Medium, or High.
Symptoms: Red X next to the provider name in Settings. Error message such as “Invalid API key” or “Authentication failed”.
Causes and solutions:
sk-ant-. For OpenAI, it starts with sk-..env, verify the variable name matches exactly (ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY). If using the alternative CLAUDE_API_KEY for Anthropic, that also works. Restart the console after changes.Symptoms: Yellow warning or timeout errors when submitting a mission. Provider Health card shows degraded status.
Causes and solutions:
Provider outage: Check the Provider Health card on the dashboard or visit the provider’s status page directly:
Network issue: Verify the console host can reach the provider’s API endpoint. Test with:
curl -s https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" -d '{}' | head -c 200If this times out, check firewalls, proxies, or DNS resolution.
Rate limiting: If you are sending many requests, the provider may throttle you. Wait a few minutes and try again, or switch to a different provider temporarily.
Symptoms: Cards show “Demo” badge and yellow outline even after adding a valid API key. Missions return pre-recorded responses.
Causes and solutions:
VITE_DEMO_MODE=true is set in your .env file or as a system environment variable. Remove it and restart the console.Symptoms: Mission submitted but no response appears. Spinner runs indefinitely.
Causes and solutions:
startup-oauth.sh is running.Symptoms: Error message “Mission timed out” or “Request exceeded maximum duration”.
Causes and solutions:
Slow cluster response: If kubectl commands against your cluster are slow, the AI mission may time out waiting for results. Test cluster responsiveness:
time kubectl --context=your-cluster get pods -AIf this takes more than a few seconds, the issue is cluster performance, not the AI.
Complex multi-cluster mission: Missions that span many clusters take longer. Break the request into per-cluster missions or target a specific cluster.
Provider latency: During peak usage, AI providers may respond slowly. Check the Provider Health card and consider switching providers.
Symptoms: “Agent disconnected” or “MCP bridge offline” message. AI missions cannot run commands.
Causes and solutions:
kc-agent not running: The agent (kc-agent) must be running for the AI to interact with clusters. If you used startup-oauth.sh, it starts automatically. Check for the process:
ps aux | grep kc-agentIf not running, restart the console with startup-oauth.sh.
Port conflict: The agent listens on port 8585 by default. Check if something else is using that port:
lsof -i :8585If there is a conflict, stop the other process or configure a different port with --port.
Plugins not installed: Verify kubestellar-ops and kubestellar-deploy are installed and accessible:
kubestellar-ops version
kubestellar-deploy versionSymptoms: The console shows zero clusters. AI missions report “No clusters available”.
Causes and solutions:
kubeconfig not found: The console reads ~/.kube/config by default. Verify it exists and contains cluster entries:
kubectl config get-contextskubeconfig not mounted (Kubernetes deployment): If running in a pod, ensure the kubeconfig is mounted as a volume. Check the Helm values for kubeconfig settings.
Cluster unreachable: The kubeconfig may reference clusters that are offline or behind a VPN. Test connectivity:
kubectl --context=your-cluster cluster-infoStale kubeconfig: If you recently changed clusters, the cached kubeconfig may be outdated. Refresh the console by clicking the refresh icon in the header or restarting the console.