# KubeStellar Console

![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/clubanderson/b9a9ae8469f1897a22d5a40629bc1e82/raw/coverage-badge.json)
[![ACMM](https://img.shields.io/endpoint?url=https%3A%2F%2Fconsole.kubestellar.io%2Fapi%2Facmm%2Fbadge%3Frepo%3Dkubestellar%252Fconsole%26v%3D3)](https://console.kubestellar.io/acmm?repo=kubestellar%2Fconsole)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/kubestellar/console/badge)](https://securityscorecards.dev/viewer/?uri=github.com/kubestellar/console)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12343/badge?v=2)](https://www.bestpractices.dev/projects/12343)
[![MTTR](https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2Fclubanderson%2F4ae525a9797e8f83231ac344fcb47226%2Fraw%2Fmedian-fix.json "Mean Time to Resolution — median time from issue filed to PR merged, updated every 5 minutes")](https://github.com/kubestellar/console/issues)

AI-powered multi-cluster Kubernetes dashboard with guided install missions for 250+ CNCF projects.

[Contributing](CONTRIBUTING.md)

![KubeStellar Console](docs/images/console-screenshot.png)

## Try it now (no install)

The fastest way to evaluate the console is the **hosted version** — no Kubernetes cluster, no install, no configuration. Demo data is built in:

> 👉 **[console.kubestellar.io](https://console.kubestellar.io)**

The hosted demo is a self-contained showcase: it serves canned demo data and intentionally **does not** talk to a local agent (`LOCAL_AGENT_HTTP_URL` is disabled in the Netlify build, so the browser cannot reach a kc-agent on your laptop). Use it to explore the UI, browse missions, and test cards without touching your machine. To work against your **own** clusters or use AI features with your own keys, you need to self-host the console — see the next section.

## Which path do I need?

| I want to… | What to do | Need a cluster? | Need to install anything? |
|---|---|---|---|
| Explore the UI / evaluate the product | [console.kubestellar.io](https://console.kubestellar.io) | no | no |
| Connect the console to **my own** clusters | [**Self-host**](#local-install-self-host) the console **and** install [**kc-agent**](#kc-agent-bridge-self-hosted-console-to-your-clusters) on the same machine | yes | yes (curl + kc-agent) |
| Self-host the console (air-gapped, custom OAuth, etc.) | [**Local install**](#local-install-self-host) | optional | yes |
| Run the console **inside** a cluster | [`deploy.sh`](deploy.sh) | yes | Helm-style script |

> **Note**: `kc-agent` is **not** consumed by the hosted demo at [console.kubestellar.io](https://console.kubestellar.io). It bridges your **self-hosted** console (running at `localhost:8080`) to your kubeconfig contexts and to AI providers. If you want the convenience of the hosted UI plus your real cluster data, you currently have to run the console locally.

## Extend with the Marketplace

KubeStellar Console can be extended with community dashboard content from the [console-marketplace](https://github.com/kubestellar/console-marketplace). The marketplace hosts dashboards, card presets, and themes for Kubernetes operations, AI/ML, security, GitOps, networking, and CNCF project integrations without adding custom code to the core console bundle.

- Browse community dashboards, card presets, and themes in [kubestellar/console-marketplace](https://github.com/kubestellar/console-marketplace)
- Share your own dashboard cards or presets through the marketplace repository
- Start from the [marketplace contribution guide](https://github.com/kubestellar/console-marketplace/blob/main/CONTRIBUTING.md) when adding new community content

## Local install (self-host)

The quickest path to a working console with your own data. `start.sh` downloads the pre-built console binary and a pre-built `kc-agent`, starts both, and opens [http://localhost:8080](http://localhost:8080):

```bash
curl -sSL https://raw.githubusercontent.com/kubestellar/console/main/start.sh | bash
```

Deploy into a cluster instead with [`deploy.sh`](deploy.sh) (`--openshift`, `--ingress <host>`, `--github-oauth`, `--uninstall`). See [docs/deploy.md](docs/deploy.md) for the full flag, environment-variable, exit-code, and example reference. For Helm chart installs that should talk to an in-cluster Kagenti backend, see [Connecting Kagenti](deploy/helm/kubestellar-console/README.md#connecting-kagenti) and the [Kagenti deployment guide](docs/kagenti-deployment-guide.md) for controller/agent topology, setup steps, and troubleshooting.

## Development

If you want to work on the repo itself, start with these entry points:

- [CLAUDE.md](CLAUDE.md) — canonical developer guide for repo structure, testing expectations, and agent rules
- [CONTRIBUTING.md](CONTRIBUTING.md) — contribution workflow, issue/PR conventions, and inventory notes
- [docs/README.md](docs/README.md) — index of the documentation tree, grouped by audience

## kc-agent (bridge self-hosted console to your clusters)

`kc-agent` is a small local HTTP/WS daemon that the **self-hosted** console talks to (default `http://127.0.0.1:8585`). It forwards requests from the browser to your kubeconfig contexts and to AI providers. The hosted demo at [console.kubestellar.io](https://console.kubestellar.io) cannot reach it (#6195) — kc-agent is only useful when you self-host.

**You do not need kc-agent** if you only want to browse the UI / demo data — just use the hosted demo. **`start.sh` already installs and launches a pre-built kc-agent for you**, so most users never need to install it manually. The instructions below are for development builds or platforms without a Homebrew formula:

**Prerequisites for kc-agent:**
- A kubeconfig that points at one or more reachable clusters (`kubectl get nodes` works locally)
- macOS, Linux, or Windows with WSL2 (see [Windows section](#windows-wsl2))

```bash
# macOS — Homebrew formula (pre-built)
brew tap kubestellar/tap && brew install kc-agent

# Linux / from source — requires Go 1.26.4+ (matches go.mod)
mkdir -p bin
go build -o bin/kc-agent ./cmd/kc-agent && ./bin/kc-agent
```

### kc-agent authentication (`KC_AGENT_TOKEN`)

`kc-agent` accepts a shared secret via `KC_AGENT_TOKEN`. When it is set, browser and WebSocket requests to the agent must present `Authorization: Bearer <token>` (or `?token=<token>` for a real WebSocket upgrade). This is recommended when you want an extra layer of protection against other local processes reaching `127.0.0.1:8585`.

- `start-dev.sh` and `startup-oauth.sh` auto-generate a random `KC_AGENT_TOKEN` for each session if you do not set one.
- Set `KC_AGENT_TOKEN` yourself if you want a stable secret across restarts or if you launch `kc-agent` manually.
- Generate one with `openssl rand -hex 32`.

```bash
export KC_AGENT_TOKEN="$(openssl rand -hex 32)"
./bin/kc-agent
```

When both the self-hosted console and `kc-agent` are running, open [http://localhost:8080](http://localhost:8080) and your local clusters appear in the cluster picker.

## Windows (WSL2)

The console install scripts and `kc-agent` are POSIX shell + Go, so they run unchanged inside WSL2. Native Windows (PowerShell / CMD) is not supported — install [WSL2 with Ubuntu](https://learn.microsoft.com/windows/wsl/install) and run everything from the WSL shell:

```powershell
# In PowerShell — one-time setup
wsl --install -d Ubuntu
```

Then from inside the Ubuntu/WSL shell. **`start.sh` only needs `curl`** — it downloads pre-built binaries, no Go toolchain required:

```bash
# Prerequisite: just curl
sudo apt-get update && sudo apt-get install -y curl

# Same install command as macOS / Linux
curl -sSL https://raw.githubusercontent.com/kubestellar/console/main/start.sh | bash
```

> **⚠️ Windows PowerShell `curl` gotcha:** In PowerShell, `curl` is an alias
> for `Invoke-WebRequest`, which behaves completely differently from the real
> curl. If you need to test endpoints from PowerShell (outside WSL), always
> use **`curl.exe`** instead of `curl`, or use the native PowerShell cmdlet:
>
> ```powershell
> # Option 1 — use curl.exe (the real curl shipped with Windows 10+)
> curl.exe -s http://localhost:8080/health
>
> # Option 2 — use PowerShell native cmdlet
> Invoke-RestMethod http://localhost:8080/health
> ```

**Building `kc-agent` from source is a separate path** — only needed if you want a development build of the agent rather than the prebuilt binary that `start.sh` already installs. It requires Go **1.26.4+** (the version pinned in `go.mod`) and `git`. Ubuntu's `golang-go` package usually lags the current release; use the [official Go install](https://go.dev/doc/install) or the `longsleep/golang-backports` PPA to get a recent version:

```bash
# add-apt-repository lives in software-properties-common — install it
# first on minimal Ubuntu/WSL images that don't ship with it.
sudo apt-get update && sudo apt-get install -y software-properties-common
sudo add-apt-repository -y ppa:longsleep/golang-backports
sudo apt-get update && sudo apt-get install -y golang-1.26 git
git clone https://github.com/kubestellar/console.git
cd console
mkdir -p bin
go build -o bin/kc-agent ./cmd/kc-agent && ./bin/kc-agent
```

Open http://localhost:8080 in your **Windows** browser — WSL2 forwards `localhost` automatically. Tracked by [#6185](https://github.com/kubestellar/console/issues/6185).

## GitHub authentication

The console uses **two** GitHub credentials (#6190). Most users need **neither** — the hosted demo works without any GitHub auth at all.

| Credential | What it does | When you need it |
|---|---|---|
| **GitHub OAuth App** (`GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET`) | Sign-in for the **self-hosted** console at `localhost:8080` | Only if you self-host the console AND want user sign-in. Skip for the hosted demo. |
| **Consolidated GitHub PAT** (a.k.a. `FeedbackGitHubToken`) | Same single PAT powers everything: nightly E2E status, community activity, leaderboard widgets, and the `/issue` page that opens GitHub issues | Optional. Without it, `/issue` returns `503 Issue submission is not available` and the GitHub-powered dashboard widgets fall back to demo data. |

**Minimum to get started**: nothing — hit [console.kubestellar.io](https://console.kubestellar.io). Everything above is opt-in.

### Setting the consolidated PAT

There are two equivalent ways to supply this PAT — pick one. Both write to the same field (`FeedbackGitHubToken` in `pkg/api/handlers/feedback.go` and `pkg/api/handlers/github_proxy.go`), so you don't need to set both:

1. **`.env` file at the repo root** — set on startup, no UI step needed:
   ```
   FEEDBACK_GITHUB_TOKEN=ghp_…
   ```

2. **Settings UI** (self-hosted only, **admin role required**) — visit Settings → GitHub Token → paste. The UI POSTs to `/api/github/token`, which is gated on the console `admin` role and persisted to `~/.kc/settings.json` by the backend. On a fresh self-hosted install, the first authenticated user is auto-bootstrapped to admin so local instances are not locked out of settings.

The hosted Netlify demo cannot persist a PAT — it has no writable local backend — so Settings UI saves don't work there. Use the env-var path for self-hosting.

### Setting up GitHub OAuth (self-hosted only)

If you self-host the console and want sign-in:

1. **Create a [GitHub OAuth App](https://github.com/settings/developers)**
   - Homepage URL: `http://localhost:8080`
   - Callback URL: `http://localhost:8080/auth/github/callback`
   - **After creating the app**, note down your **Client ID** (visible immediately) and generate a **Client Secret** (click "Generate a new client secret")

2. **Clone the repo** (if you haven't already):
   ```bash
   git clone https://github.com/kubestellar/console.git
   cd console
   ```

3. **Create a `.env` file in the repo root** (`console/.env`):
   ```bash
   # Create .env file with your GitHub OAuth App credentials
   cat > .env << 'EOF'
   GITHUB_CLIENT_ID=your-client-id-here
   GITHUB_CLIENT_SECRET=your-client-secret-here
   EOF
   ```
   
   **Replace `your-client-id-here` and `your-client-secret-here`** with the actual values from your GitHub OAuth App (step 1).
   
   **⚠️ Common mistakes:**
   - **Missing `.env` file**: The console looks for `.env` in the repo root (`console/.env`), not in your home directory or elsewhere.
   - **Wrong credentials**: Client ID and Client Secret must match **exactly** what GitHub shows in your OAuth App settings. Copy-paste to avoid typos.
   - **Expired secret**: If you regenerate the Client Secret in GitHub, you must update `.env` with the new value.
   
   **Troubleshooting OAuth errors:**
   - `"invalid client credentials"` → Verify `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` in your `.env` match your GitHub OAuth App at https://github.com/settings/developers
   - `"redirect_uri_mismatch"` → The Callback URL in your GitHub OAuth App must be exactly `http://localhost:8080/auth/github/callback`

4. **Start the console**:
   ```bash
   ./startup-oauth.sh
   ```

Open http://localhost:8080 and sign in with GitHub. For Kubernetes deployments, pass `--github-oauth` to `deploy.sh` instead.

### Consolidated PAT scopes

Whichever path you used above (env var or Settings UI), the [Personal Access Token](https://github.com/settings/tokens) needs **either**:
- A **classic** PAT with the `repo` scope, **or**
- A **fine-grained** PAT with both **Issues: Read & Write** *and* **Contents: Read & Write** (verified against `pkg/api/handlers/feedback.go:71` — Contents is required, not just Issues).

## AI configuration

The console can use AI for adaptive card suggestions and mission help. AI is **optional** — the UI, missions, and dashboards all work without any AI keys configured (#6191).

**Important**: AI BYOK only works on the **self-hosted** console. The hosted demo at [console.kubestellar.io](https://console.kubestellar.io) explicitly disables `LOCAL_AGENT_HTTP_URL` (verified in `web/src/lib/constants/network.ts`), so the browser cannot reach a local agent there. To use your own AI keys, self-host the console first.

### Supported kc-agent providers (CLI-based and operator-controlled LLMs)

`kc-agent` uses **local CLI providers** and **operator-controlled OpenAI-compatible / self-hosted LLMs** for AI features that need cluster-aware tool execution. Raw vendor API keys such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GOOGLE_API_KEY` do **not** make Anthropic/OpenAI/Gemini available as mission-capable `kc-agent` providers in the current build. Those variables are documented later for backend/Stellar paths and source-level provider configuration, while `kc-agent` itself still relies on the tooling model described in [`docs/security/SECURITY-MODEL.md`](docs/security/SECURITY-MODEL.md#3-local--self-hosted-llms).

**Recommended setup paths:**

1. **CLI-based agents** (with full tool execution capabilities):
   ```bash
   # Install Claude Desktop or claude CLI — https://claude.ai/download
   # Install Gemini CLI — follow official Google AI SDK instructions
   # Install GitHub Copilot CLI — gh extension install github/gh-copilot
   # Install other CLI agents: codex, antigravity, goose, bob
   
   # kc-agent will auto-detect installed CLI agents — no env vars needed
   ./bin/kc-agent
   ```

2. **Local/self-hosted LLM servers** (OpenAI-compatible endpoints):
   ```bash
   # Ollama (local)
   export OLLAMA_URL=http://127.0.0.1:11434
   export OLLAMA_MODEL=llama3.2
   
   # Open WebUI (self-hosted gateway)
   export OPEN_WEBUI_URL=https://your-openwebui.example.com
   export OPEN_WEBUI_API_KEY=your-key
   export OPEN_WEBUI_MODEL=gpt-4
   
   # Other supported: llama.cpp, LocalAI, vLLM, LM Studio, Red Hat AI Inference Server
   # See docs/security/SECURITY-MODEL.md for the full list
   
   ./bin/kc-agent
   ```

> **Why are Anthropic/OpenAI/Gemini API keys not enough for `kc-agent`?** The agent registry intentionally excludes those upstream API-key providers because they cannot execute cluster commands AND they route traffic to a specific vendor endpoint that the operator has no control over. The console's mission and diagnostic flows require tool-capable agents that can run `kubectl`, `helm`, and other commands locally. See `pkg/agent/registry.go:378-384` for the rationale.

> **What do the README API-key variables enable?** `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GOOGLE_API_KEY` are relevant to backend/Stellar provider configuration and source-level HTTP-provider support, while `GROQ_API_KEY` and `OPENROUTER_API_KEY` enable registered **chat-only** providers. None of those variables replace the CLI-based setup above when you need `kc-agent` missions or other tool-executing workflows.

> **A note on the Settings → API Keys modal**: The console UI exposes a "Manage Keys" button under **Settings → API Keys**. This modal is wired to the agent's `/settings/keys` endpoint, but in the current build that endpoint returns an empty providers list (`providers := []providerDef{}` in `pkg/agent/server_operations.go:288`) because API-key-driven agents are hidden there. **Use the CLI-based or local LLM setup paths above for `kc-agent` features.**

**If no supported AI provider is configured**, AI-powered features fall back to deterministic / rule-based behavior. The card suggestions, missions, and dashboards remain fully usable.

**Security model, air-gapped deployments, and local / self-hosted LLMs** are covered in [`docs/security/SECURITY-MODEL.md`](docs/security/SECURITY-MODEL.md). That document explains the data flow between browser, Go backend, kc-agent, and AI providers; how to run the console with no external AI access; and the currently supported self-hosted path using kc-agent's CLI-based agents.

## How It Works

1. **Onboarding** — Sign in with GitHub, answer role questions, get a personalized dashboard
2. **Adaptive AI** — Tracks card interactions and suggests swaps when your focus shifts (Claude, OpenAI, or Gemini)
3. **MCP Bridge** — Queries cluster state (pods, deployments, events, drift, security) via `kubestellar-ops` and `kubestellar-deploy`
4. **Missions** — Step-by-step guided installs with pre-flight checks, validation, troubleshooting, and rollback
5. **Real-time** — WebSocket-powered live event streaming from all connected clusters

## Stellar (Persistent AI Operations Runtime — Alpha)

**Stellar** extends the console from request/response AI interactions into a **persistent operational runtime** with mission continuity, memory, and proactive execution. It brings autonomous operations capabilities to KubeStellar with support for multi-step mission planning, long-term memory, event-driven triggers, and policy-enforced tool execution.

Key capabilities:
- **Persistent missions** — Store and re-run multi-step operational tasks (rollouts, incident response, scaling decisions)
- **Operational memory** — Learn from incidents, postmortems, and rollout history
- **Event-driven triggers** — Respond to Kubernetes events, Prometheus alerts, webhooks, or schedules
- **RBAC-aware execution** — Tool runtime validates permissions before cluster actions
- **Structured auditing** — Full audit trail of prompts, decisions, tools, and outputs

**Note:** Stellar is alpha/experimental. Architecture and APIs are subject to change.

For implementation details, see [docs/stellar/architecture.md](docs/stellar/architecture.md).

## Architecture

See the full [Architecture documentation](https://kubestellar.io/docs/console/overview/architecture) on the KubeStellar website.

### Related Repositories

- **[console-kb](https://github.com/kubestellar/console-kb)** — Knowledge base of guided installers for 250+ CNCF projects and solutions to common Kubernetes problems
- **[console-marketplace](https://github.com/kubestellar/console-marketplace)** — Community-contributed monitoring cards per CNCF project
- **[kc-agent](cmd/kc-agent/)** — Local agent bridging the browser to kubeconfig, coding agents (Codex, Copilot, Claude CLI), and MCP servers (`kubestellar-ops`, `kubestellar-deploy`)
- **[claude-plugins](https://github.com/kubestellar/claude-plugins)** — Claude Code marketplace plugins for Kubernetes
- **[homebrew-tap](https://github.com/kubestellar/homebrew-tap)** — Homebrew formulae for KubeStellar tools
- **[KubeStellar](https://kubestellar.io)** — Multi-cluster configuration management

## Quality Assurance

Console uses AI tools (GitHub Copilot, Claude Code) to accelerate development. Quality is maintained through **layered feedback loops** — every PR triggers the same automated checks regardless of author, and continuous monitoring catches what PR checks miss.

- **Before commit**: TypeScript build + Go build + 5 post-build safety checks + lint
- **Before merge**: nil-safety, ts-null-safety, array-safety, API contract, Playwright E2E, coverage gate, TTFI performance, CodeQL, Copilot code review, UI/UX standards scanner, visual regression
- **Visual regression**: 18 UI components documented as Storybook stories with theme support. Playwright captures screenshots and diffs against baselines on every PR that touches UI components.
- **After merge**: Targeted Playwright tests run against production (`console.kubestellar.io`); failures reopen the original issue
- **Continuous**: Hourly coverage (12 shards), 4x daily QA, nightly E2E, nightly security scanning, real-time GA4 error tracking, UI/UX standards nightly scan

When a regression class is identified, a maintainer adds an automated check to the earliest possible loop. See [docs/AI-QUALITY-ASSURANCE.md](docs/AI-QUALITY-ASSURANCE.md) for the full breakdown.

## Environment Variables Reference

The console and kc-agent use many configurable environment variables. This section provides a consolidated reference for all available options. See [.env.example](.env.example) for a complete example file with all commented defaults.

### GitHub Authentication & Integration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GITHUB_CLIENT_ID` | ✓ (if using GitHub OAuth) | — | GitHub OAuth App Client ID. Create at https://github.com/settings/developers |
| `GITHUB_CLIENT_SECRET` | ✓ (if using GitHub OAuth) | — | GitHub OAuth App Client Secret. Keep this secret — never commit to version control |
| `FEEDBACK_GITHUB_TOKEN` | Optional | — | GitHub Personal Access Token (PAT) for programmatic issue creation and screenshot uploads. Can be classic (repo scope) or fine-grained (Issues + Contents read/write). Used by feedback/contribute dialog and GitHub-powered dashboard widgets |
| `FEEDBACK_REPO_OWNER` | Optional | `kubestellar` | GitHub repository owner for feedback issue creation |
| `FEEDBACK_REPO_NAME` | Optional | `console` | GitHub repository name for feedback issue creation |
| `GITHUB_WEBHOOK_SECRET` | Optional | — | Secret for validating GitHub webhooks. Generate with `openssl rand -hex 32` |
| `GITHUB_MUTATIONS_TOKEN` | Optional | — | GitHub PAT for re-running or canceling pipelines. Requires workflow scope |
| `GITHUB_REPO` | Optional | `kubestellar/console` | GitHub repository for update checks |

### Development & UI Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DEV_MODE` | Optional | `true` | Enable development mode features and debug logging |
| `FRONTEND_URL` | Optional | `http://localhost:5174` | Frontend base URL for backend redirects. Must match the frontend's listening URL |
| `SKIP_ONBOARDING` | Optional | `false` | Skip the onboarding questionnaire for new users (useful for testing/demos) |
| `VITE_DEMO_MODE` | Optional | `false` | Enable demo/preview mode with mock data (build-time only) |
| `VITE_API_BASE_URL` | Optional | — | API base URL override for frontend backend calls. Leave empty to use same origin. Build-time only |
| `VITE_NO_LOCAL_AGENT` | Optional | `false` | Disable local kc-agent in the frontend. Build-time only |
| `VITE_GEOCODING_API_URL` | Optional | `https://geocoding-api.open-meteo.com/v1/search` | Geocoding API endpoint for weather card location search |
| `VITE_GOOGLE_FONTS_API_URL` | Optional | — | Google Fonts API URL override. Build-time only |
| `ENABLED_DASHBOARDS` | Optional | — | Comma-separated list of dashboard IDs to show in sidebar. Empty = show all. Affects display order |

### Kubernetes & Cluster Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `KUBECONFIG` | Optional | `~/.kube/config` | Path to kubeconfig file for kubectl access |
| `CLUSTER_NAME` | Optional | — | Override the cluster name displayed in the console. Auto-detected from kubeconfig if not set |
| `NO_LOCAL_AGENT` | Optional | `false` | Suppress local kc-agent connections (for in-cluster deployments that use backend directly) |

### AI API Keys — backend features and chat-only providers

These variables are **not all equivalent**:

- `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GOOGLE_API_KEY` document backend/Stellar and source-level HTTP-provider configuration, but they do **not** make Anthropic/OpenAI/Gemini available as mission-capable `kc-agent` providers in the current build.
- `GROQ_API_KEY` and `OPENROUTER_API_KEY` enable registered **chat-only** providers for analysis/chat workflows; they still do not power `kc-agent` missions or other tool-executing flows.
- For `kc-agent` tool execution, use the CLI-based or operator-controlled local/self-hosted providers described above and in [`docs/security/SECURITY-MODEL.md`](docs/security/SECURITY-MODEL.md#3-local--self-hosted-llms).

Without any supported AI provider, the console falls back to deterministic/rule-based behavior.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ANTHROPIC_API_KEY` | Optional | — | Anthropic Claude API key from https://console.anthropic.com/settings/keys |
| `CLAUDE_MODEL` | Optional | `claude-sonnet-4-5-20250514` | Claude model selection |
| `OPENAI_API_KEY` | Optional | — | OpenAI GPT API key from https://platform.openai.com/api-keys |
| `OPENAI_MODEL` | Optional | `gpt-4-turbo` | OpenAI model selection |
| `GOOGLE_API_KEY` | Optional | — | Google Gemini API key from https://makersuite.google.com/app/apikey |
| `GEMINI_MODEL` | Optional | `gemini-2.0-flash` | Google Gemini model selection |
| `OPENROUTER_API_KEY` | Optional | — | OpenRouter unified API key from https://openrouter.ai/keys (supports many models) |
| `OPENROUTER_MODEL` | Optional | `openai/gpt-4o-mini` | OpenRouter model selection. See https://openrouter.ai/models for catalog |
| `OPENROUTER_BASE_URL` | Optional | — | Custom base URL for self-hosted OpenRouter proxies |
| `GROQ_API_KEY` | Optional | — | Groq LPU inference API key from https://console.groq.com/keys |
| `GROQ_MODEL` | Optional | `llama-3.3-70b-versatile` | Groq model selection. See https://console.groq.com/docs/models |
| `GROQ_BASE_URL` | Optional | — | Custom base URL for self-hosted Groq proxies |
| `DEFAULT_AGENT` | Optional | — | Default AI provider if multiple are configured. Options: `claude`, `openai`, `gemini`, `openrouter`, `groq`. Auto-detected if not set |

### Local/Self-Hosted LLM Servers

Use for air-gapped deployments or local model serving without external vendor APIs.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `OLLAMA_BASE_URL` | Optional | `http://localhost:11434` | Ollama server endpoint for local LLM inference |
| `OPEN_WEBUI_URL` | Optional | — | Open WebUI self-hosted gateway URL |
| `OPEN_WEBUI_API_KEY` | Optional | — | Open WebUI API key for authentication |

### Stellar Assistant Configuration

The Stellar assistant provides intelligent operational insights. Configuration is optional.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `STELLAR_DEFAULT_PROVIDER` | Optional | `ollama` | Default provider for `/api/stellar/ask` and `/api/stellar/digest` |
| `STELLAR_DEFAULT_MODEL` | Optional | `llama3` | Default model selection |
| `STELLAR_WATCHER_INTERVAL` | Optional | `30s` | Polling interval for Stellar event watcher |
| `STELLAR_QUIET_START` | Optional | — | Quiet hours start time (HH:MM format) for suppressing non-urgent alerts |
| `STELLAR_QUIET_END` | Optional | — | Quiet hours end time (HH:MM format) |
| `STELLAR_DIGEST_HOUR` | Optional | — | Hour of day for digest generation (0-23) |
| `STELLAR_ENCRYPTION_KEY` | Optional | — | Encryption key for sensitive Stellar data storage |
| `STELLAR_FALLBACK_PROVIDER` | Optional | — | Fallback provider if default is unavailable |

### kc-agent Authentication & Configuration

`kc-agent` is the local bridge between the console and your clusters/AI providers.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `KC_AGENT_TOKEN` | Optional | — | Shared secret for securing kc-agent WebSocket access. Generate with `openssl rand -hex 32`. If unset, `start-dev.sh` and `startup-oauth.sh` auto-generate per session |
| `KC_DEV_MODE` | Optional | `false` | Enable kc-agent development mode with verbose logging |
| `KC_ALLOWED_ORIGINS` | Optional | — | CORS-allowed origins for WebSocket connections (comma-separated) |

### Service Discovery — KAgent & KAgenti Integration

For in-cluster KAgent/KAgenti service discovery. Use controller URLs to skip discovery. For full KAgenti deployment patterns, warnings, and troubleshooting, see the [Kagenti deployment guide](docs/kagenti-deployment-guide.md).

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `KAGENT_CONTROLLER_URL` | Optional | — | Direct KAgent controller URL (skips service discovery) |
| `KAGENT_NAMESPACE` | Optional | — | Kubernetes namespace where KAgent runs |
| `KAGENT_SERVICE_NAME` | Optional | — | Kubernetes service name for KAgent |
| `KAGENT_SERVICE_PORT` | Optional | — | Service port for KAgent |
| `KAGENT_SERVICE_PROTOCOL` | Optional | `http` | Service protocol (http/https) |
| `KAGENTI_CONTROLLER_URL` | Optional | — | Direct KAgenti controller URL (skips service discovery) |
| `KAGENTI_AGENT_URL` | Optional | — | KAgenti agent endpoint |
| `KAGENTI_AGENT_NAME` | Optional | — | KAgenti agent name |
| `KAGENTI_AGENT_NAMESPACE` | Optional | — | Kubernetes namespace for KAgenti agent |
| `KAGENTI_NAMESPACE` | Optional | — | Kubernetes namespace where KAgenti controller runs |
| `KAGENTI_SERVICE_NAME` | Optional | — | Kubernetes service name for KAgenti |
| `KAGENTI_SERVICE_PORT` | Optional | — | Service port for KAgenti |
| `KAGENTI_SERVICE_PROTOCOL` | Optional | `http` | Service protocol (http/https) |

### GPU Metrics & Alerting

Enable GPU monitoring and set utilization thresholds.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GPU_METRICS_ENABLED` | Optional | `false` | Enable GPU metrics collection |
| `GPU_METRICS_DCGM_ENABLED` | Optional | `false` | Enable NVIDIA DCGM exporter scraping (requires NVIDIA GPU Operator) |
| `GPU_METRICS_DCGM_NAMESPACE` | Optional | `gpu-operator` | Kubernetes namespace where DCGM exporter runs |
| `GPU_METRICS_DCGM_SERVICE` | Optional | `dcgm-exporter` | Service name of the DCGM exporter |
| `GPU_UTIL_OVER_THRESHOLD` | Optional | `90` | Alert when GPU utilization exceeds this percentage |
| `GPU_UTIL_UNDER_THRESHOLD` | Optional | `20` | Alert when GPU utilization falls below this percentage |
| `GPU_UTIL_POLL_INTERVAL_MS` | Optional | `1200000` | GPU metrics polling interval in milliseconds (default: 20 minutes) |

### ArgoCD Integration

Connect the console to an ArgoCD instance for deployment tracking and synchronization.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ARGOCD_AUTH_TOKEN` | Optional | — | ArgoCD API authentication token. Generate via: `argocd account generate-token --account admin` |
| `ARGOCD_SERVER_URL` | Optional | — | ArgoCD server URL for API access |
| `ARGOCD_TLS_INSECURE` | Optional | `false` | Disable TLS certificate verification (dev/test only with self-signed certs) |

### GitHub Pipelines & CI/CD

Monitor and control GitHub Actions workflows.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PIPELINE_REPOS` | Optional | — | Comma-separated list of GitHub repositories to monitor (format: `owner/repo,owner/repo2`) |
| `ACMM_REPOS` | Optional | `PIPELINE_REPOS` or the built-in KubeStellar repos | Comma-separated list of GitHub repositories the ACMM scan and badge endpoints may query |
| `GITHUB_MUTATIONS_TOKEN` | Optional | — | GitHub PAT for re-running or canceling pipeline runs (requires `workflow` scope) |

### Analytics & Telemetry

Configure analytics and measurement.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GA4_REAL_MEASUREMENT_ID` | Optional | — | Real GA4 Measurement ID (frontend uses a decoy ID; the proxy rewrites it) |
| `VITE_GA_MEASUREMENT_ID` | Optional | — | Frontend GA4 Measurement ID (build-time only) |

### Server Configuration

Core backend and network settings.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PORT` | Optional | `8080` | Backend listening port |
| `DATABASE_PATH` | Optional | `./console.db` | Path to SQLite database file |
| `MAX_BODY_BYTES` | Optional | `5242880` | Global HTTP request body size limit in bytes (default: 5 MB) |
| `WS_MAX_CONNECTIONS` | Optional | `1000` | WebSocket connection limit (prevents resource exhaustion) |

### TLS Configuration

Enable HTTPS/TLS for secure connections.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `TLS_ENABLED` | Optional | `false` | Enable HTTPS with TLS certificates |
| `TLS_CERT_FILE` | Optional | — | Path to TLS certificate file (PEM format) |
| `TLS_KEY_FILE` | Optional | — | Path to TLS private key file (PEM format) |

### In-Cluster Deployment

Configuration for running the console inside a Kubernetes cluster.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `POD_NAMESPACE` | Optional | — | Kubernetes namespace where console pod runs (used for self-upgrade feature) |

### DRASI Integration (Experimental)

Reactive graph subscription for real-time data.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `VITE_DRASI_SERVER_URL` | Optional | — | DRASI server URL (build-time only) |
| `VITE_DRASI_PLATFORM_CLUSTER` | Optional | — | DRASI platform cluster identifier (build-time only) |
| `KC_DRASI_SERVER_ALLOWED_HOSTS` | Optional | — | Comma-separated Drasi server hosts/IPs allowed for `/api/drasi/proxy?target=server`; required to permit loopback or private hosts |

### Quick Setup Examples

**Minimal local development (no OAuth, demo user):**
```bash
./start-dev.sh
```

**With GitHub OAuth:**
```bash
cat > .env << 'EOF'
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
EOF
./startup-oauth.sh
```

**With backend Anthropic credentials:**
```bash
cat > .env << 'EOF'
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
ANTHROPIC_API_KEY=your-anthropic-key
EOF
./startup-oauth.sh
```

This config is useful for backend/Stellar provider paths, but `kc-agent` missions still require a supported CLI-based provider or operator-controlled local/self-hosted endpoint.

**With local Ollama:**
```bash
export OLLAMA_BASE_URL=http://localhost:11434
./start-dev.sh
```

**With Kubernetes kubeconfig:**
```bash
export KUBECONFIG=~/.kube/config
./start-dev.sh
```

For more examples and detailed setup instructions, see the [Getting Started](#local-install-self-host) and [GitHub Authentication](#github-authentication) sections above.

## License

Apache License 2.0 — see [LICENSE](LICENSE).