docs(readme): clarify hosted vs local, kc-agent, GitHub auth, AI (#6188-#6191)#6193
Merged
clubanderson merged 1 commit intomainfrom Apr 10, 2026
Merged
docs(readme): clarify hosted vs local, kc-agent, GitHub auth, AI (#6188-#6191)#6193clubanderson merged 1 commit intomainfrom
clubanderson merged 1 commit intomainfrom
Conversation
… AI config (#6188-#6191) Bundled fix for four README clarity reports from @rishi-jat: #6188 — Lead with the hosted demo, not the install command. Adds a 'Try it now (no install)' section at the very top pointing at console.kubestellar.io, plus a 'Which path do I need?' decision table that maps user intent (evaluate / connect own cluster / self-host / in-cluster) to the right action and clearly states what each path requires. #6189 — Explain kc-agent prerequisites and context. New 'kc-agent (connect the hosted console to your clusters)' section explicitly says kc-agent is only required if you want the hosted console to read *your* clusters, that you do NOT need it just to browse the UI / demo data, and lists the actual prerequisites (working kubeconfig, OS). #6190 — Differentiate the three GitHub credentials. New 'GitHub authentication' section opens with a table comparing OAuth App (self- hosted sign-in only), Settings UI PAT (optional widgets), and FEEDBACK_GITHUB_TOKEN (issue submission), with a clear 'Minimum to get started: nothing' line so users know they don't need any of them for the hosted demo. #6191 — Document AI configuration. New 'AI configuration' section states AI is optional, walks through the Settings -> API Keys -> Manage Keys flow (which posts to local kc-agent, not the hosted backend), lists the env-var fallback (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY), notes BYOK is safe to use with console.kubestellar.io because keys never leave the local agent, and states the no-key fallback behavior. Closes #6188, closes #6189, closes #6190, closes #6191. Signed-off-by: Andrew Anderson <[email protected]>
kubestellar-prow
Bot
added
the
dco-signoff: yes
Contributor
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
✅ Deploy Preview for kubestellarconsole canceled.
|
Contributor
|
👋 Hey @clubanderson — thanks for opening this PR!
This is an automated message. |
kubestellar-prow
Bot
added
the
size/M
Contributor
There was a problem hiding this comment.
Pull request overview
Restructures the top of README.md to guide first-time users through the hosted demo vs local/self-hosted setup decision, and adds clearer sections for kc-agent usage, GitHub auth options, and AI key configuration.
Changes:
- Adds a “Try it now (no install)” intro and a decision table mapping user intent to the right setup path.
- Rewrites kc-agent guidance with prerequisites and clarifies when it’s needed.
- Adds new comparison-style docs for GitHub authentication methods and AI API key configuration.
Comment on lines
+25
to
33
| | Explore the UI / evaluate the product | [console.kubestellar.io](https://console.kubestellar.io) | no | no | | ||
| | See the hosted console talk to **my own** clusters | Install [**kc-agent**](#kc-agent-connect-the-hosted-console-to-your-clusters) | yes | kc-agent only | | ||
| | Self-host the console (air-gapped, custom OAuth, etc.) | [**Local install**](#local-install-self-host) | optional | yes (Go + bash) | | ||
| | Run the console **inside** a cluster | [`deploy.sh`](deploy.sh) | yes | Helm-style script | | ||
|
|
||
| ## kc-agent (connect the hosted console to your clusters) | ||
|
|
||
| `kc-agent` is a small local bridge — it forwards [console.kubestellar.io](https://console.kubestellar.io) requests to the kubeconfig contexts on your laptop. It is **only** required if you want the hosted console to read live data from clusters you control (#6189). | ||
|
|
There was a problem hiding this comment.
The decision table and kc-agent section imply that installing kc-agent lets the hosted UI at console.kubestellar.io connect to a local agent. In the current web build, LOCAL_AGENT_WS_URL/LOCAL_AGENT_HTTP_URL are intentionally disabled when hostname is console.kubestellar.io, so the hosted UI will not talk to a locally running kc-agent. Please either adjust the README to say kc-agent is for local/self-hosted installs, or change the hosted build behavior to allow agent connectivity.
|
|
||
| ```bash | ||
| brew tap kubestellar/tap && brew install kc-agent # macOS | ||
| go build -o bin/kc-agent ./cmd/kc-agent && ./bin/kc-agent # Linux (Go 1.24+) |
There was a problem hiding this comment.
The README states Go 1.24+ for building/running (Linux + WSL), but go.mod declares go 1.25.0, which generally requires a Go 1.25 toolchain. Please align the stated Go version in these prerequisites with the repository’s actual minimum version.
Suggested change
| go build -o bin/kc-agent ./cmd/kc-agent && ./bin/kc-agent # Linux (Go 1.24+) | |
| go build -o bin/kc-agent ./cmd/kc-agent && ./bin/kc-agent # Linux (Go 1.25+) |
|
|
||
| ```bash | ||
| brew tap kubestellar/tap && brew install kc-agent # macOS | ||
| go build -o bin/kc-agent ./cmd/kc-agent && ./bin/kc-agent # Linux (Go 1.24+) |
There was a problem hiding this comment.
go build -o bin/kc-agent ... will fail on a fresh clone if the bin/ directory doesn’t exist. Consider either creating the directory as part of the instructions or using an approach that doesn’t require a pre-existing output directory (e.g., go install to GOPATH/bin).
Suggested change
| go build -o bin/kc-agent ./cmd/kc-agent && ./bin/kc-agent # Linux (Go 1.24+) | |
| mkdir -p bin && go build -o bin/kc-agent ./cmd/kc-agent && ./bin/kc-agent # Linux (Go 1.24+) |
| | Credential | What it does | Where it lives | When you need it | | ||
| |---|---|---|---| | ||
| | **GitHub OAuth App** (`GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET`) | Sign-in for the **self-hosted** console at `localhost:8080` | `.env` file at the repo root | Only if you self-host the console AND want user sign-in. Skip for the hosted demo. | | ||
| | **GitHub PAT in Settings UI** | Powers nightly E2E status, community activity, leaderboard widgets | Settings page → "GitHub Token" field (browser only, not on disk) | Optional. Adds GitHub-powered widgets to your dashboard. | |
There was a problem hiding this comment.
The table claims the GitHub PAT entered in the Settings UI is “browser only, not on disk”. In practice, settings (including feedbackGithubToken) are persisted via the local agent to an on-disk settings file (encrypted at rest) and also cached in localStorage for sync. Please update this description so users have accurate expectations about where the token is stored.
Suggested change
| | **GitHub PAT in Settings UI** | Powers nightly E2E status, community activity, leaderboard widgets | Settings page → "GitHub Token" field (browser only, not on disk) | Optional. Adds GitHub-powered widgets to your dashboard. | | |
| | **GitHub PAT in Settings UI** | Powers nightly E2E status, community activity, leaderboard widgets | Entered in Settings → "GitHub Token"; persisted via the local agent in the on-disk settings file (encrypted at rest) and also cached in `localStorage` for sync | Optional. Adds GitHub-powered widgets to your dashboard. | |
| ``` | ||
|
|
||
| The token needs a classic `repo` scope **or** a fine-grained token with **Issues: Read & Write**. Without it, issue submission returns `503 Issue submission is not available`. | ||
| The token needs a classic `repo` scope **or** a fine-grained token with **Issues: Read & Write**. |
There was a problem hiding this comment.
The fine-grained PAT permissions for FEEDBACK_GITHUB_TOKEN are documented as “Issues: Read & Write” only, but the server-side error message indicates it also requires “Contents” read/write permissions. Please update the documented required scopes to match the backend’s actual requirements.
Suggested change
| The token needs a classic `repo` scope **or** a fine-grained token with **Issues: Read & Write**. | |
| The token needs a classic `repo` scope **or** a fine-grained token with **Issues: Read & Write** and **Contents: Read & Write**. |
Comment on lines
+136
to
+142
| **How to add API keys:** | ||
|
|
||
| 1. Make sure `kc-agent` is running locally (see [kc-agent](#kc-agent-connect-the-hosted-console-to-your-clusters)) | ||
| 2. Open the console → **Settings** → **API Keys** → **Manage Keys** | ||
| 3. Paste a key from one of: [OpenAI](https://platform.openai.com/api-keys), [Anthropic Claude](https://console.anthropic.com/settings/keys), or [Google Gemini](https://aistudio.google.com/apikey) | ||
|
|
||
| Keys are sent only to your **local** `kc-agent` process and stored in its config file — they never reach the hosted backend, so BYOK is safe to use with [console.kubestellar.io](https://console.kubestellar.io). You can also pre-set keys via environment variables before launching `kc-agent`: |
There was a problem hiding this comment.
This section suggests users can manage AI keys while using console.kubestellar.io and that keys are sent to a local kc-agent. However, the hosted build disables LOCAL_AGENT_HTTP_URL, so the Settings → API Keys flow won’t be able to reach a local agent from console.kubestellar.io. Please clarify the supported flow (local/self-hosted only) or update the product behavior to match these docs.
Suggested change
| **How to add API keys:** | |
| 1. Make sure `kc-agent` is running locally (see [kc-agent](#kc-agent-connect-the-hosted-console-to-your-clusters)) | |
| 2. Open the console → **Settings** → **API Keys** → **Manage Keys** | |
| 3. Paste a key from one of: [OpenAI](https://platform.openai.com/api-keys), [Anthropic Claude](https://console.anthropic.com/settings/keys), or [Google Gemini](https://aistudio.google.com/apikey) | |
| Keys are sent only to your **local** `kc-agent` process and stored in its config file — they never reach the hosted backend, so BYOK is safe to use with [console.kubestellar.io](https://console.kubestellar.io). You can also pre-set keys via environment variables before launching `kc-agent`: | |
| **How to add API keys (local / self-hosted console only):** | |
| The **Settings → API Keys → Manage Keys** flow requires a console instance that can reach your local `kc-agent`. This is supported when you are running the console locally or self-hosted alongside `kc-agent`. The hosted demo at [console.kubestellar.io](https://console.kubestellar.io) does **not** support sending API keys to a local agent. | |
| 1. Make sure `kc-agent` is running locally (see [kc-agent](#kc-agent-connect-the-hosted-console-to-your-clusters)) | |
| 2. Open your local or self-hosted console → **Settings** → **API Keys** → **Manage Keys** | |
| 3. Paste a key from one of: [OpenAI](https://platform.openai.com/api-keys), [Anthropic Claude](https://console.anthropic.com/settings/keys), or [Google Gemini](https://aistudio.google.com/apikey) | |
| Keys are sent only to your **local** `kc-agent` process and stored in its config file — they never reach the hosted backend. You can also pre-set keys via environment variables before launching `kc-agent`: |
Contributor
|
Thank you for your contribution! Your PR has been merged. Check out what's new:
Stay connected: Slack #kubestellar-dev | Multi-Cluster Survey |
Contributor
|
Post-merge build verification passed ✅ Both Go and frontend builds compiled successfully against merge commit |
clubanderson
added a commit
that referenced
this pull request
Apr 10, 2026
Six factual corrections from Copilot review of #6193, all verified against source before changing: 1. Hosted demo CANNOT talk to a local kc-agent (#6195 main point). Verified in web/src/lib/constants/network.ts: LOCAL_AGENT_HTTP_URL is set to '' on the Netlify build (the _isNetlify check explicitly includes 'console.kubestellar.io'), so the browser can never reach 127.0.0.1:8585. Restructured the top of the README: - Removed the false 'kc-agent connects hosted UI to your clusters' decision-table row. - Added an explicit note in the Try-it-now section that the hosted demo is self-contained and serves canned data. - Renamed the kc-agent section to make clear it bridges the SELF-HOSTED console (not the hosted UI) to your kubeconfig and AI providers. - Reordered so 'Local install (self-host)' comes BEFORE the kc-agent section, since you need to self-host before kc-agent becomes useful. 2. Go version was still 1.24+ in one spot. Bumped to 1.25+ to match go.mod's `go 1.25.0`. (Already fixed in #6194 for the WSL block; this catches the Linux line in the kc-agent section.) 3. `go build -o bin/kc-agent ...` fails on a fresh clone if bin/ doesn't exist. Added `mkdir -p bin` to both build snippets. 4. The 'GitHub PAT in Settings UI' row claimed it was 'browser only, not on disk'. Wrong — APIKeySettings.tsx POSTs the token to kc-agent's /settings/keys endpoint, which persists to disk. Also added that the Settings flow only works when self-hosting, since the hosted build disables LOCAL_AGENT_HTTP_URL. 5. FEEDBACK_GITHUB_TOKEN fine-grained scopes: I documented only 'Issues: Read & Write'. Verified against pkg/api/handlers/feedback.go which requires both 'Issues' AND 'Contents' read/write. Updated. 6. AI configuration section wrongly claimed BYOK works with the hosted demo. Same root cause as #1 — the Settings → API Keys flow needs LOCAL_AGENT_HTTP_URL, which is empty on Netlify. Rewrote the section to state up front that BYOK only works self-hosted, and reordered the steps so 'self-host first' is step 1. Closes #6195. Signed-off-by: Andrew Anderson <[email protected]>
clubanderson
added a commit
that referenced
this pull request
Apr 10, 2026
#6197) Six factual corrections from Copilot review of #6193, all verified against source before changing: 1. Hosted demo CANNOT talk to a local kc-agent (#6195 main point). Verified in web/src/lib/constants/network.ts: LOCAL_AGENT_HTTP_URL is set to '' on the Netlify build (the _isNetlify check explicitly includes 'console.kubestellar.io'), so the browser can never reach 127.0.0.1:8585. Restructured the top of the README: - Removed the false 'kc-agent connects hosted UI to your clusters' decision-table row. - Added an explicit note in the Try-it-now section that the hosted demo is self-contained and serves canned data. - Renamed the kc-agent section to make clear it bridges the SELF-HOSTED console (not the hosted UI) to your kubeconfig and AI providers. - Reordered so 'Local install (self-host)' comes BEFORE the kc-agent section, since you need to self-host before kc-agent becomes useful. 2. Go version was still 1.24+ in one spot. Bumped to 1.25+ to match go.mod's `go 1.25.0`. (Already fixed in #6194 for the WSL block; this catches the Linux line in the kc-agent section.) 3. `go build -o bin/kc-agent ...` fails on a fresh clone if bin/ doesn't exist. Added `mkdir -p bin` to both build snippets. 4. The 'GitHub PAT in Settings UI' row claimed it was 'browser only, not on disk'. Wrong — APIKeySettings.tsx POSTs the token to kc-agent's /settings/keys endpoint, which persists to disk. Also added that the Settings flow only works when self-hosting, since the hosted build disables LOCAL_AGENT_HTTP_URL. 5. FEEDBACK_GITHUB_TOKEN fine-grained scopes: I documented only 'Issues: Read & Write'. Verified against pkg/api/handlers/feedback.go which requires both 'Issues' AND 'Contents' read/write. Updated. 6. AI configuration section wrongly claimed BYOK works with the hosted demo. Same root cause as #1 — the Settings → API Keys flow needs LOCAL_AGENT_HTTP_URL, which is empty on Netlify. Rewrote the section to state up front that BYOK only works self-hosted, and reordered the steps so 'self-host first' is step 1. Closes #6195. Signed-off-by: Andrew Anderson <[email protected]>
clubanderson
added a commit
that referenced
this pull request
Apr 10, 2026
…6185 follow-up) @rishi-jat reported (#6185) that the README install instructions had no Windows path. That was fixed in #6187/#6193/#6194/#6197/#6207, but the README is only one surface — the in-app modals that show up when users first try to set up kc-agent had no Windows option either. This PR adds parity between the README and both in-app modals. AgentSetupDialog.tsx (the welcome modal that auto-shows when no agent is connected and the user hasn't dismissed it): - New windowsBuildCommand constant: `apt-get install software-properties-common` -> longsleep PPA -> `golang-1.25` -> git clone -> `mkdir -p bin` -> `go build`. Single line so users can paste it once into their WSL shell. - New Windows (WSL2) collapsible section parallel to the existing Linux one. Same Eye/click pattern, same Copy button + 'Copied' feedback (UI_FEEDBACK_TIMEOUT_MS), shares the existing toast timer cleanup pattern via copiedWindowsTimerRef. - Linux build command also updated: bumped to include 'mkdir -p bin' so a fresh clone doesn't fail (#6196 caught this for the README). InClusterAgentDialog.tsx (the in-cluster connect dialog): - Same WINDOWS_WSL_INSTALL_CMD constant + new Windows (WSL2) collapsible section parallel to the build-from-source one. New COPY_KEY_WSL=102 in the existing key range. - Linux build-from-source command updated similarly: 'mkdir -p bin' added, label changed from 'Go 1.24+' to 'Go 1.25+' to match go.mod. Both Windows sections include: - The one-time PowerShell prerequisite (`wsl --install -d Ubuntu`) described inline so users don't have to leave the modal - A note that http://localhost:8080 just works in the Windows browser because WSL2 forwards localhost - A pointer back to the README's step-by-step version This closes the in-app gap rishi-jat originally reported. The README + in-app modals are now consistent for the four supported install paths: macOS Homebrew, Linux build-from-source, Windows WSL2 build, in-cluster deploy. Verified: `npm run build` clean. Refs #6185. Signed-off-by: Andrew Anderson <[email protected]>
3 tasks
clubanderson
added a commit
that referenced
this pull request
Apr 10, 2026
…6185 follow-up) (#6238) * feat(setup): add Windows (WSL2) section to in-app agent setup modals (#6185 follow-up) @rishi-jat reported (#6185) that the README install instructions had no Windows path. That was fixed in #6187/#6193/#6194/#6197/#6207, but the README is only one surface — the in-app modals that show up when users first try to set up kc-agent had no Windows option either. This PR adds parity between the README and both in-app modals. AgentSetupDialog.tsx (the welcome modal that auto-shows when no agent is connected and the user hasn't dismissed it): - New windowsBuildCommand constant: `apt-get install software-properties-common` -> longsleep PPA -> `golang-1.25` -> git clone -> `mkdir -p bin` -> `go build`. Single line so users can paste it once into their WSL shell. - New Windows (WSL2) collapsible section parallel to the existing Linux one. Same Eye/click pattern, same Copy button + 'Copied' feedback (UI_FEEDBACK_TIMEOUT_MS), shares the existing toast timer cleanup pattern via copiedWindowsTimerRef. - Linux build command also updated: bumped to include 'mkdir -p bin' so a fresh clone doesn't fail (#6196 caught this for the README). InClusterAgentDialog.tsx (the in-cluster connect dialog): - Same WINDOWS_WSL_INSTALL_CMD constant + new Windows (WSL2) collapsible section parallel to the build-from-source one. New COPY_KEY_WSL=102 in the existing key range. - Linux build-from-source command updated similarly: 'mkdir -p bin' added, label changed from 'Go 1.24+' to 'Go 1.25+' to match go.mod. Both Windows sections include: - The one-time PowerShell prerequisite (`wsl --install -d Ubuntu`) described inline so users don't have to leave the modal - A note that http://localhost:8080 just works in the Windows browser because WSL2 forwards localhost - A pointer back to the README's step-by-step version This closes the in-app gap rishi-jat originally reported. The README + in-app modals are now consistent for the four supported install paths: macOS Homebrew, Linux build-from-source, Windows WSL2 build, in-cluster deploy. Verified: `npm run build` clean. Refs #6185. Signed-off-by: Andrew Anderson <[email protected]> * test(ui-ux): bump EXPECTED_RAW_HEX_COUNT 282→284 for #6185 ref Signed-off-by: Andrew Anderson <[email protected]> --------- Signed-off-by: Andrew Anderson <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Bundled fix for four README clarity reports from @rishi-jat (in-app feedback flow). All four are about the same theme — the README dropped users straight into install commands and never explained the decision space. This restructures the top of the README so a first-time visitor sees the hosted demo and a decision table BEFORE any install instructions.
FEEDBACK_GITHUB_TOKENand states minimum to get started: nothingANTHROPIC_API_KEY,OPENAI_API_KEY,GOOGLE_API_KEY), notes BYOK is safe with hosted demo because keys live in local kc-agent only, and states the no-key fallback behaviorI verified the AI claims against
pkg/agent/config.go(env var names) andweb/src/components/agent/APIKeySettings.tsx(the Settings UI POSTs toKC_AGENT_URL/settings/keys, so keys really do stay on the local agent and never reach the hosted backend).Closes #6188, closes #6189, closes #6190, closes #6191.