Local Setup Guide

This guide walks you through running KubeStellar Console from source on your local machine for development or evaluation. For production deployments, see the Installation page.

Prerequisites

Install kubestellar-mcp Plugins

The console requires kubestellar-ops and kubestellar-deploy MCP plugins. Install them via the Claude Code Marketplace or Homebrew:

Option A: Claude Code Marketplace (recommended)

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

Then install kubestellar-ops and kubestellar-deploy from the Discover tab.

Option B: Homebrew

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

See the kubestellar-mcp documentation for details.

Clone the Repository

git clone https://github.com/kubestellar/console.git
cd console

Option 1: Without OAuth (Development Mode)

The simplest way to run the console locally. No GitHub credentials needed — a local dev-user session is created automatically.

./start-dev.sh

This script:

1. Checks for Go and Node.js prerequisites
2. Kills any processes using ports 8080 and 5174
3. Compiles and starts the Go backend on port 8080
4. Installs npm dependencies (cd web && npm install)
5. Starts the Vite dev server on port 5174
6. Creates a local dev-user session (no GitHub login)

Open http://localhost:5174

The Vite dev server proxies API requests to the Go backend on port 8080.

Option 2: With GitHub OAuth (Full Auth Flow)

For multi-user deployments or to test the complete authentication flow.

💡 New: Setup Wizard (Recommended)

As of v0.3.18, you can skip the manual steps below. Simply start the console without OAuth credentials:

./startup-oauth.sh

Visit http://localhost:8080 and the login page will show an interactive Setup Wizard that walks you through creating a GitHub OAuth App, with copy-to-clipboard buttons for all values. You can also choose “Continue in Demo Mode” to skip OAuth entirely.

The manual steps below are still available if you prefer to configure OAuth before first startup.

Step 1: Create a GitHub OAuth App

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

Step 2: Create .env File

Create a .env file in the repository root (same directory as startup-oauth.sh):

GITHUB_CLIENT_ID=your_client_id_here
GITHUB_CLIENT_SECRET=your_client_secret_here

Important: The .env file must be in the same directory as startup-oauth.sh. The script reads it from its own directory. The file is .gitignored so your credentials are never committed.

Step 3: Start the Console

./startup-oauth.sh

This script:

1. Loads environment variables from .env
2. Kills any processes using ports 8080 and 8585
3. Starts the kc-agent (MCP + WebSocket server on port 8585)
4. Builds the frontend (cd web && npm run build)
5. Starts the Go backend on port 8080, serving both the API and the built frontend

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

Note: With startup-oauth.sh, the Go backend serves both the API and the pre-built frontend on port 8080. There is no separate Vite dev server (port 5174 is not used).

Environment Variables

Required for OAuth Mode

Optional

Port Reference

Startup Scripts Comparison

Working with Worktrees

If you are working on multiple feature branches simultaneously, use git worktrees to avoid conflicts:

cd /path/to/console
git worktree add /tmp/console-my-feature -b my-feature-branch
cd /tmp/console-my-feature/web
npm install  # worktrees share git but NOT node_modules
cd /tmp/console-my-feature
./startup-oauth.sh  # or ./start-dev.sh

Troubleshooting

Port Already in Use

If you see “address already in use” errors:

# Find and kill processes on the ports
lsof -i :8080 | grep LISTEN
lsof -i :5174 | grep LISTEN
kill -9 <PID>

Both startup scripts attempt to clean up stale port processes automatically.

”MCP bridge failed to start”

The kubestellar-mcp plugins are not installed. Install them with Homebrew or the Claude Code Marketplace:

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

“GITHUB_CLIENT_SECRET is not set”

You are running startup-oauth.sh without a .env file. Either:

1. Create a .env file with your OAuth credentials (see Step 2 above)
2. Or use ./start-dev.sh instead — it does not require OAuth credentials

Clusters Not Showing

1. Verify your kubeconfig has accessible clusters: kubectl config get-contexts
2. Test connectivity: kubectl --context=your-cluster get nodes
3. Check that kubestellar-mcp binaries are in your PATH: which kubestellar-ops

Stale Frontend After Code Changes

If using start-dev.sh, the Vite dev server provides hot module replacement. If using startup-oauth.sh, you must restart the script after changing frontend code (it rebuilds on startup).

Next Steps

• Features Guide — Explore all console features
• Architecture — Understand how the components work together
• Authentication — Deep dive into OAuth and session behavior
• Configuration — Customize AI mode, themes, and more