---
title: "Quick Start — Get the Multi-Cluster Kubernetes Dashboard Running in Minutes"
linkTitle: "Quick Start"
weight: 1
description: >
  Get KubeStellar Console running in minutes. Start managing multi-cluster Kubernetes operations with AI Missions, 120+ monitoring cards, and fleet-wide deployment automation — no complex setup required.
keywords:
  - kubernetes quick start
  - multi-cluster kubernetes setup
  - kubernetes dashboard quick start
  - kubernetes management tool getting started
  - AI kubernetes operations setup
---

# 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](https://console.kubestellar.io) - no installation needed.

!!! info "Claude Code is optional (recommended for AI features)"
    This Quick Start optionally uses **[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)**, 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](#install-kubestellar-mcp-tools) below.

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

```bash
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:

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

| Option | Description |
|--------|-------------|
| `--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:

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

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

## What You Need

| Component | What it is | Required? |
|-----------|------------|-----------|
| kubestellar-mcp plugins | Connect to your clusters | Yes — install separately (Step 1) |
| kubeconfig | Your cluster credentials | Yes |
| Frontend + Backend | The console itself | Yes (included in the console executable) |
| GitHub OAuth App | Lets users sign in via GitHub | Optional |

See the [Architecture](architecture.md) 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](https://claude.com/product/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](windows-11-local-source-build-troubleshooting.md) for Vite proxy, OAuth redirect, and kubeconfig-specific fixes.

### WSL2 Setup Steps

1. **Install WSL2** (if not already installed):
   
   ```powershell
   wsl --install
   ```

2. **Install Ubuntu** (or your preferred distribution):
   
   ```powershell
   wsl --install -d Ubuntu
   ```

3. **Update packages** inside WSL:
   
   ```bash
   sudo apt update && sudo apt upgrade -y
   ```

4. **Install prerequisites** inside WSL:
   
   ```bash
   # 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](../kubestellar-mcp/overview/intro.md) for full details.

**Install the binaries (required):**

```bash
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](https://docs.anthropic.com/en/docs/claude-code/overview) and want AI Missions, also register the plugins in Claude Code:

```text
/plugin marketplace add kubestellar/claude-plugins
```

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

Verify installation:

```bash
# 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

### Option A: Pre-Built Binaries (recommended)

```bash
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)

```bash
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](https://github.com/settings/developers) → 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:
   
   ```bash
   GITHUB_CLIENT_ID=your_client_id
   GITHUB_CLIENT_SECRET=your_client_secret
   ```

3. Start the console:
   
   ```bash
   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](cluster-registration.md).

## 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](https://github.com/settings/developers) → 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:
   
   ```bash
   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:

    ```bash
    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

```bash
# 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

```bash
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

```bash
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:

```bash
# 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:

```bash
brew uninstall kubestellar-ops kubestellar-deploy
```

### Source Build

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

### Helm / Kubernetes Deployment

```bash
helm uninstall ksc --namespace ksc
kubectl delete namespace ksc
```

## Next Steps

- [Installation](installation.md) - Full deployment options (Helm, Docker, OpenShift)
- [Configuration](configuration.md) - Customize AI mode, token limits, and more
- [Architecture](architecture.md) - Understand how the 7 components work together
- [Dashboards](dashboards.md) - Explore the 20+ dashboard pages
- [Cards](all-cards.md) - See all 120+ card types
- [kubestellar-mcp Documentation](../kubestellar-mcp/overview/intro.md) - Deep dive into kubestellar-ops and kubestellar-deploy
