Installation

This guide covers all deployment options for KubeStellar Console.

Try it first! See a live preview at kubestellarconsole.netlify.app

Fastest Path command downloads pre-built binaries, starts the backend + agent, and opens your browser:

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

This typically takes under 45 seconds. No OAuth or GitHub credentials required — you get a local dev-user session automatically.

System Components

KubeStellar Console has 6 components that work together:

  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌──────────────┐
  │  1. GitHub  │   │ 2. Frontend │   │ 3. Backend  │   │   4. Agent   │
  │  OAuth App  │──▶│  (React UI) │◀─▶│    (Go)     │──▶│ (MCP Bridge) │
  │ (optional)  │   │             │   │             │   │              │
  │  Login via  │   │  Dashboard, │   │  API server,│   │  Talks to    │
  │  GitHub     │   │  cards, AI  │   │  auth, data │   │  clusters    │
  └─────────────┘   └─────────────┘   └─────────────┘   └───────┬──────┘
                                                                │
  ┌─────────────────────────────────────────────────────────────┤
  │                 5. Claude Code Plugins                      │
  │                                                             │
  │  ┌─────────────────────┐   ┌──────────────────────────┐     │
  │  │   kubestellar-ops   │   │   kubestellar-deploy     │     │
  │  │  - List clusters    │   │  - Deploy apps           │     │
  │  │  - Find pod issues  │   │  - GitOps sync           │     │
  │  │  - Check security   │   │  - Scale apps            │     │
  │  │  - Analyze RBAC     │   │  - Check drift           │     │
  │  └─────────────────────┘   └──────────────────────────┘     │
  └─────────────────────────────────────────────────────────────┤
                                                                │
  ┌─────────────────────────────────────────────────────────────▼───┐
  │                         6. Kubeconfig                           │
  │     ~/.kube/config with access to your clusters                 │
  │     [cluster-1]   [cluster-2]   [cluster-3]   [cluster-n]       │
  └─────────────────────────────────────────────────────────────────┘

Component Summary

#	Component	What it does	Required?
1	GitHub OAuth App	Lets users sign in with GitHub	Optional — without it, a local `dev-user` session is created
2	Frontend	React web app you see in browser	Yes — bundled in console image
3	Backend	Go server that handles API calls	Yes — bundled in console image
4	Agent (MCP Bridge)	Connects backend to your clusters	Yes — bundled in console image
5	Claude Code Plugins	kubestellar-ops + kubestellar-deploy tools	Yes — Claude Marketplace or Homebrew
6	Kubeconfig	Your cluster credentials	Yes — your existing `~/.kube/config`

Installation Steps

Step 1: Install Claude Code Plugins

The console uses kubestellar-mcp plugins to talk to your clusters. See the full kubestellar-mcp documentation for details.

Option A: Install from Claude Code Marketplace (recommended)

# In Claude Code, run:
/plugin marketplace add kubestellar/claude-plugins

Then:

Go to /plugin → Marketplaces tab → click Update
Go to /plugin → Discover tab
Install kubestellar-ops and kubestellar-deploy

Verify with /mcp - you should see:

plugin:kubestellar-ops:kubestellar-ops · ✓ connected
plugin:kubestellar-deploy:kubestellar-deploy · ✓ connected

Option B: Install via Homebrew (source: homebrew-tap)

brew tap kubestellar/tap
brew install kubestellar-ops kubestellar-deploy

Step 2: Set Up Kubeconfig

The console reads clusters from your kubeconfig. Make sure you have access:

# List your clusters
kubectl config get-contexts
 
# Test access to a cluster
kubectl --context=your-cluster get nodes

To add more clusters, merge kubeconfigs:

KUBECONFIG=~/.kube/config:~/.kube/cluster2.yaml kubectl config view --flatten > ~/.kube/merged
mv ~/.kube/merged ~/.kube/config

Step 3: Deploy the Console

Choose your deployment method:

Curl-liner - Fastest, downloads pre-built binaries
Run from source (no OAuth) - For development, no GitHub credentials needed
Run from source (with OAuth) - Full GitHub login experience
Helm (Kubernetes) - Production deployment
OpenShift - OpenShift with Routes
Docker - Single-node or development

Curl Quickstart

Downloads pre-built binaries and starts the console:

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

This starts the backend (port 8080) and opens the frontend in your browser. No OAuth credentials needed — a local dev-user session is created automatically.

Run from Source

For contributors or if you want to build from source. No GitHub OAuth required.

Prerequisites

Go 1.24+
Node.js 20+
kubestellar-ops and kubestellar-deploy installed (see Step 1)

Setup

git clone https://github.com/kubestellar/console.git
cd console
./start-dev.sh

This compiles the Go backend, installs npm dependencies, starts a Vite dev server on port 5174, and creates a local dev-user session (no GitHub login needed).

Open http://localhost:5174

Run from Source with OAuth

To enable GitHub login (for multi-user deployments or to test the full auth flow):

1. Create a GitHub OAuth App

Go to GitHub Developer Settings → OAuth Apps → New OAuth App
Fill in:
- Application name: KubeStellar Console
- Homepage URL: http://localhost:8080
- Authorization callback URL: http://localhost:8080/auth/github/callback
Click Register application
Copy the Client ID and generate a Client Secret

2. Configure Environment

Create a .env file in the project root with these two variables:

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

3. Start the Console

git clone https://github.com/kubestellar/console.git
cd console
./startup-oauth.sh

Open http://localhost:5174 and sign in with GitHub.

Tip: running, click your profile avatar → the Developer panel shows your OAuth status, console version, and quick links.

Environment	Callback URL
Local dev	`http://localhost:8080/auth/github/callback`
Kubernetes	`https://console.your-domain.com/auth/github/callback`
OpenShift	`https://ksc.apps.your-cluster.com/auth/github/callback`

Helm Installation

1. Add Secrets

Create a secret with your OAuth credentials:

kubectl create namespace ksc
 
kubectl create secret generic ksc-secrets \
  --namespace ksc \
  --from-literal=github-client-id=YOUR_CLIENT_ID \
  --from-literal=github-client-secret=YOUR_CLIENT_SECRET

Optionally add Claude API key for AI features:

kubectl create secret generic ksc-secrets \
  --namespace ksc \
  --from-literal=github-client-id=YOUR_CLIENT_ID \
  --from-literal=github-client-secret=YOUR_CLIENT_SECRET \
  --from-literal=claude-api-key=YOUR_CLAUDE_API_KEY

2. Install Chart

From GitHub Container Registry:

helm install ksc oci://ghcr.io/kubestellar/charts/console \
  --namespace ksc \
  --set github.existingSecret=ksc-secrets

From source:

git clone https://github.com/kubestellar/console.git
cd console
 
helm install ksc ./deploy/helm/kubestellar-console \
  --namespace ksc \
  --set github.existingSecret=ksc-secrets

3. Access the Console

Port forward (development):

kubectl port-forward -n ksc svc/ksc 8080:8080

Open http://localhost:8080

Ingress (production):

helm upgrade ksc ./deploy/helm/kubestellar-console \
  --namespace ksc \
  --set github.existingSecret=ksc-secrets \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=ksc.your-domain.com

OpenShift Installation

OpenShift uses Routes instead of Ingress:

helm install ksc ./deploy/helm/kubestellar-console \
  --namespace ksc \
  --set github.existingSecret=ksc-secrets \
  --set route.enabled=true \
  --set route.host=ksc.apps.your-cluster.com

The console will be available at https://ksc.apps.your-cluster.com

Docker Installation

For single-node or development deployments:

docker run -d \
  --name ksc \
  -p 8080:8080 \
  -e GITHUB_CLIENT_ID=your_client_id \
  -e GITHUB_CLIENT_SECRET=your_client_secret \
  -v ~/.kube:/root/.kube:ro \
  -v ksc-data:/app/data \
  ghcr.io/kubestellar/console:latest

Kubernetes Deployment via Script command that handles helm, secrets, and ingress:

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

Supports --context, --openshift, --ingress <host>, and --github-oauth flags.

Multi-Cluster Access

The console reads clusters from your kubeconfig. To access multiple clusters:

Merge kubeconfigs:

KUBECONFIG=~/.kube/config:~/.kube/cluster2.yaml kubectl config view --flatten > ~/.kube/merged
mv ~/.kube/merged ~/.kube/config

Mount merged config in container/pod
Verify access:
```
kubectl config get-contexts
```

Upgrading

helm upgrade ksc oci://ghcr.io/kubestellar/charts/console \
  --namespace ksc \
  --reuse-values

Uninstalling

helm uninstall ksc --namespace ksc
kubectl delete namespace ksc

Troubleshooting

”MCP bridge failed to start”

Cause: kubestellar-ops or kubestellar-deploy plugins are not installed.

Solution: Follow Step 1: Install Claude Code Plugins or see the full kubestellar-mcp documentation.

# Via Homebrew
brew tap kubestellar/tap
brew install kubestellar-ops kubestellar-deploy

GitHub OAuth 404 or Blank Page

Cause: OAuth credentials not configured correctly.

Solutions:

Verify the secret contains correct credentials
Check callback URL matches exactly (see Run from Source with OAuth)
View pod logs: kubectl logs -n ksc deployment/ksc

”GITHUB_CLIENT_SECRET is not set”

Cause: You’re running startup-oauth.sh without a .env file.

Solutions:

Create a .env file with GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET (see Run from Source with OAuth)
Or use ./start-dev.sh instead — it doesn’t require OAuth credentials

Cause: The Client Secret is wrong or has been regenerated.

Solutions:

Go to GitHub Developer Settings → your OAuth App
Generate a new Client Secret
Update GITHUB_CLIENT_SECRET in your .env file
Restart the console

”csrf_validation_failed”

Cause: The callback URL in GitHub doesn’t match the console’s URL.

Solutions:

Verify the Authorization callback URL in your GitHub OAuth App settings matches exactly: http://localhost:8080/auth/github/callback
Clear your browser cookies for localhost
Restart the console

Clusters Not Showing

Cause: kubeconfig not mounted or MCP bridge not running.

Solutions:

Verify kubeconfig is mounted in the pod
Check MCP bridge status in logs
Verify kubestellar-mcp tools are installed: which kubestellar-ops kubestellar-deploy

Plugin Shows Disconnected

Cause: Binary not in PATH or not working.

Solutions:

Verify binary is installed: which kubestellar-ops
Verify binary works: kubestellar-ops version
Restart Claude Code

See kubestellar-mcp troubleshooting for more details.

kubestellar-mcp Documentation - Full guide to kubestellar-ops and kubestellar-deploy plugins
Architecture - How the console components work together
Configuration - AI mode, token limits, and customization
Quick Start - Get running in 5 minutes

Installation

Fastest Path command downloads pre-built binaries, starts the backend + agent, and opens your browser:

System Components

Component Summary

Installation Steps

Step 1: Install Claude Code Plugins

Step 2: Set Up Kubeconfig

Step 3: Deploy the Console

Curl Quickstart

Run from Source

Prerequisites

Setup

Run from Source with OAuth

1. Create a GitHub OAuth App

2. Configure Environment

3. Start the Console

Helm Installation

1. Add Secrets

2. Install Chart

3. Access the Console

OpenShift Installation

Docker Installation

Kubernetes Deployment via Script command that handles helm, secrets, and ingress:

Multi-Cluster Access

Upgrading

Uninstalling

Troubleshooting

”MCP bridge failed to start”

GitHub OAuth 404 or Blank Page

”GITHUB_CLIENT_SECRET is not set”

”exchange_failed” After GitHub Login

”csrf_validation_failed”

Clusters Not Showing

Plugin Shows Disconnected

Related Documentation