Compose a PRView SourceOpen Issue

Quick Start — Multi-Cluster Kubernetes in Minutes

Get KubeStellar Console running locally for development or evaluation.

Try it first! See a live preview at console.kubestellar.io - no installation needed.

!!! info “Claude Code is optional (recommended for AI features)” This Quick Start optionally uses Claude Code, Anthropic’s CLI tool, for AI Missions. Claude Code requires an Anthropic API subscription.

What requires Claude Code:

  • AI Missions (automated issue detection and remediation)
  • Registering kubestellar-mcp plugins in Claude Code’s plugin system

What works without Claude Code:

  • The console dashboard, cards, and multi-cluster views all work without Claude Code
  • The kubestellar-mcp binaries are installed via Homebrew (required for all users)
  • The curl quickstart and source builds do not require Claude Code themselves

Fastest Path (curl)

Prerequisites: You must install the kubestellar-mcp plugins before running this command — they are not installed by start.sh. See Install Kubestellar-mcp Tools below.

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

curl -H "Cache-Control: no-cache" -sSL https://raw.githubusercontent.com/kubestellar/console/main/start.sh | bash

This downloads and starts the console only. It does not install kubestellar-mcp plugins. Typically under 45 seconds. No GitHub OAuth credentials required — a local dev-user session is created automatically.

CLI Options (start.sh)

Pass options after bash -s -- when using the curl quickstart:

curl -H "Cache-Control: no-cache" -sSL https://raw.githubusercontent.com/kubestellar/console/main/start.sh | bash -s -- --port 9090
OptionDescription
--version, -v <tag>Download and run a specific release tag instead of the latest stable release.
--channel, -c <name>Select the update channel: stable or unstable. Defaults to ~/.kc/settings.json if present, otherwise stable.
--dir, -d <path>Install into a custom directory instead of ./kubestellar-console.
--port, -p <port>Run the console on a custom local port instead of 8080.

kc-agent Daemon Lifecycle

When start.sh runs, it launches kc-agent as a background daemon with nohup.

  • kc-agent keeps running if you press Ctrl+C or close the terminal.
  • The PID is written to <install-dir>/kc-agent.pid.
  • Logs are written to <install-dir>/kc-agent.log.
  • If you run start.sh again, it checks the PID file, stops any existing kc-agent, and restarts it with the newly downloaded binary.
  • When the console exits, start.sh tells you that kc-agent continues running in the background.

To stop the daemon manually:

kill $(cat ./kubestellar-console/kc-agent.pid)

If you installed to a different directory with --dir, use that path instead.

What You Need

ComponentWhat it isRequired?
kubestellar-mcp pluginsConnect to your clustersYes — install separately (Step 1)
kubeconfigYour cluster credentialsYes
Frontend + BackendThe console itselfYes (included in the console executable)
GitHub OAuth AppLets users sign in via GitHubOptional

See the Architecture page for the full system diagram and component details.

Prerequisites

  • kubectl configured with at least one cluster

  • kubestellar-mcp plugins (see below)

  • For source builds: Go 1.25+ and Node.js 20+

  • For AI features only: Claude Code CLI (optional) or an API key from Anthropic, OpenAI, or Google

Windows/WSL Setup

For Windows users, we recommend using Windows Subsystem for Linux (WSL2) for the best experience.

If you are running from source on Windows 11, also see Windows 11 Local Source Build Troubleshooting for Vite proxy, OAuth redirect, and kubeconfig-specific fixes.

WSL2 Setup Steps

  1. Install WSL2 (if not already installed):

    wsl --install

  2. Install Ubuntu (or your preferred distribution):

    wsl --install -d Ubuntu

  3. Update packages inside WSL:

    sudo apt update && sudo apt upgrade -y

  4. Install prerequisites inside WSL:

    # Install Node.js
curl -H "Cache-Control: no-cache" -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
 
# Install Go
wget https://go.dev/dl/go1.25.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.25.0.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc
 
# Install kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

  5. Follow the standard setup instructions from within your WSL environment.

Note: Access your kubeconfig from Windows by mounting the Windows file system at /mnt/c/ in WSL.

Install kubestellar-mcp Tools

The console uses kubestellar-mcp plugins to talk to your clusters. This step is required and must be done before running the console. See kubestellar-mcp documentation for full details.

Install the binaries (required):

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

This puts the tools on your PATH so the console’s MCP bridge can find them.

Additionally, register with Claude Code (needed for AI Missions):

If you use Claude Code and want AI Missions, also register the plugins in Claude Code:

/plugin marketplace add kubestellar/claude-plugins

Then go to /plugin → Discover tab and install kubestellar-ops and kubestellar-deploy.

Verify installation:

# Check binaries are on PATH (required)
which kubestellar-ops && which kubestellar-deploy
 
# If using Claude Code, type /mcp to see both plugins connected (optional)

Run the Console

curl -H "Cache-Control: no-cache" -sSL https://raw.githubusercontent.com/kubestellar/console/main/start.sh | bash

This downloads the console binary, starts the backend (port 8080), and opens your browser. It does not install kubestellar-mcp plugins — complete the kubestellar-mcp installation section first.

Option B: Run From Source (No OAuth)

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

Compiles from source and starts a Vite dev server on port 5174. No GitHub credentials needed.

Option C: Run From Source with GitHub OAuth

If you want GitHub login (for multi-user or testing the full auth flow):

  1. Create a GitHub OAuth App at GitHub Developer Settings → OAuth Apps → New OAuth App:

    • Application name: KubeStellar Console (dev)
    • Homepage URL: http://localhost:8080
    • Authorization callback URL: http://localhost:8080/auth/github/callback

  2. Create a .env file in the project root:

    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:8080 and sign in with GitHub.

!!! note “Port difference between startup scripts” startup-oauth.sh serves both the API and pre-built frontend on port 8080 (Go backend). There is no separate Vite dev server. start-dev.sh uses a Vite dev server on port 5174 for hot-reload during development.

Access the Console

Open http://localhost:8080 (curl quickstart or startup-oauth.sh) or http://localhost:5174 (start-dev.sh source builds).

Your clusters from ~/.kube/config appear automatically. If running with OAuth, sign in with GitHub. Without OAuth, you’re logged in as dev-user.

If you need the full kubeconfig-driven registration flow, including required kubeconfig fields, single vs. multiple context behavior, and auth expectations, see Cluster Registration.

Kubernetes Deployment

Before proceeding with the installation, you need to configure GitHub OAuth, which the application uses for access control.

  1. Create a GitHub OAuth App at GitHub Developer Settings → OAuth Apps → New OAuth App:

    • Application name: KubeStellar Console (dev)
    • Homepage URL: http://localhost:8080
    • Authorization callback URL: http://localhost:8080/auth/github/callback

  2. Create a .env file in the project root:

    GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

  3. Export the environment variables into your current shell so subsequent kubectl and helm commands can reference them:

    export $(cat .env | xargs)

    Note: This only makes the variables available within the current shell session. It does not create Kubernetes Secrets. To create a Kubernetes Secret from these values, use kubectl create secret as shown in the next section.

After completing the previous GitHub OAuth setup, proceed to the next section.

Using Helm

# Create namespace and secrets
kubectl create namespace ksc
 
kubectl create secret generic ksc-secrets \
  --namespace ksc \
  --from-literal=github-client-id=$GITHUB_CLIENT_ID \
  --from-literal=github-client-secret=$GITHUB_CLIENT_SECRET
 
# Install chart
helm install ksc oci://ghcr.io/kubestellar/charts/kubestellar-console \
  --namespace ksc \
  --set github.existingSecret=ksc-secrets
 
# Expose the Kubestellar service
kubectl port-forward -n ksc svc/ksc-kubestellar-console 8080:8080

Using Deploy Script

curl -H "Cache-Control: no-cache" -sSL https://raw.githubusercontent.com/kubestellar/console/main/deploy.sh | bash

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

OpenShift

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

Cleanup / Uninstall

Curl Quickstart (start.sh)

The script downloads a binary to a local directory (typically ./kubestellar-console/). To remove it:

# Stop the running console:
# - Press Ctrl+C in the terminal where it's running, OR
# - Kill processes on the specific ports:
kill $(lsof -ti:8080) 2>/dev/null || true
kill $(lsof -ti:5174) 2>/dev/null || true
 
# Stop the background kc-agent daemon (if still running)
kill $(cat ./kubestellar-console/kc-agent.pid) 2>/dev/null || true
 
# Remove downloaded files
rm -rf ./kubestellar-console/

The kubestellar-mcp plugins are managed separately by Claude Code — use /plugin → your plugin manager to uninstall them, or via Homebrew:

brew uninstall kubestellar-ops kubestellar-deploy

Source Build

# Stop the running processes (Ctrl+C), then remove the cloned directory
rm -rf ./console

Helm / Kubernetes Deployment

helm uninstall ksc --namespace ksc
kubectl delete namespace ksc

Next Steps