docs(readme): correct hosted-build limits + AI/PAT/scope facts (#6195)#6197
Merged
clubanderson merged 1 commit intomainfrom Apr 10, 2026
Merged
docs(readme): correct hosted-build limits + AI/PAT/scope facts (#6195)#6197clubanderson merged 1 commit intomainfrom
clubanderson merged 1 commit intomainfrom
Conversation
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]>
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
This PR updates README.md to correct several factual statements about hosted vs self-hosted behavior, kc-agent installation prerequisites (including Go version), GitHub token persistence, required PAT scopes, and AI key configuration—based on the repo’s current implementation.
Changes:
- Clarifies that the hosted demo is self-contained and cannot connect to a local kc-agent.
- Updates kc-agent build prerequisites (Go 1.25+) and avoids fresh-clone build failures by creating
bin/first. - Revises GitHub credential scope/persistence details and adjusts AI BYOK guidance to require self-hosting.
| |---|---|---|---| | ||
| | **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. | | ||
| | **GitHub PAT in Settings UI** | Powers nightly E2E status, community activity, leaderboard widgets | Saved by the local `kc-agent` to its on-disk settings file (not browser-only). Only reachable when self-hosting — the hosted Netlify build disables `LOCAL_AGENT_HTTP_URL`, so the Settings page cannot persist a token there. | Optional. Adds GitHub-powered widgets to your **self-hosted** dashboard. | |
There was a problem hiding this comment.
The "GitHub PAT in Settings UI" row says the token is saved by the local kc-agent and that the hosted build fails because LOCAL_AGENT_HTTP_URL is disabled. In the current code, the Settings UI saves this token via the console backend endpoints (POST /api/github/token in GitHubTokenSection.tsx), which persist to the encrypted ~/.kc/settings.json via the settings manager (not via the agent URL). Please update the README row to match the actual persistence path and the real reason it doesn’t work on the hosted demo (no writable local backend/settings file on Netlify).
Suggested change
| | **GitHub PAT in Settings UI** | Powers nightly E2E status, community activity, leaderboard widgets | Saved by the local `kc-agent` to its on-disk settings file (not browser-only). Only reachable when self-hosting — the hosted Netlify build disables `LOCAL_AGENT_HTTP_URL`, so the Settings page cannot persist a token there. | Optional. Adds GitHub-powered widgets to your **self-hosted** dashboard. | | |
| | **GitHub PAT in Settings UI** | Powers nightly E2E status, community activity, leaderboard widgets | Persisted by the console backend to the encrypted local settings file at `~/.kc/settings.json` (not browser-only). Only works when self-hosting — the hosted Netlify demo has no writable local backend/settings file, so the Settings page cannot persist a token there. | Optional. Adds GitHub-powered widgets to your **self-hosted** dashboard. | |
Comment on lines
+152
to
+159
| **How to add API keys (self-hosted):** | ||
|
|
||
| 1. Self-host the console (see [Local install](#local-install-self-host)) | ||
| 2. Make sure `kc-agent` is running locally (the same `start.sh` already starts one for you) | ||
| 3. Open the local console → **Settings** → **API Keys** → **Manage Keys** | ||
| 4. 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) | ||
|
|
||
| 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 POSTed from the browser to your **local** `kc-agent` process (`http://127.0.0.1:8585/settings/keys`) and stored in its on-disk settings file. They never reach any hosted backend. |
There was a problem hiding this comment.
This section instructs users to add OpenAI/Anthropic/Gemini keys via Settings → API Keys → Manage Keys, but the agent endpoint that backs this UI currently returns an empty provider list (providers := []providerDef{} in pkg/agent/server_operations.go:284-288), so the modal will render no providers and users can’t actually enter keys. Either adjust the README to describe only the environment-variable path for now, or update the agent to return the intended providers so the UI flow works as documented.
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
…rs, software-properties-common (#6196, #6198) Three Copilot review nits across two PRs, all verified against source: 1. #6196 / README:78 — sudo add-apt-repository assumes software-properties-common is installed, but minimal Ubuntu/WSL images don't ship with it. Added an explicit apt-get install line for software-properties-common, plus -y to add-apt-repository so the whole snippet runs unattended. 2. #6198 / README:102 — I claimed the GitHub PAT in the Settings UI is 'Saved by the local kc-agent to its on-disk settings file'. Wrong. Verified against web/src/components/settings/sections/GitHubTokenSection.tsx:57+ and pkg/api/server.go:692-694: GitHubTokenSection POSTs to /api/github/token, which is handled by the **console backend** (pkg/api/handlers/github_proxy.go), NOT by kc-agent. The token is persisted to ~/.kc/settings.json by the backend's settings manager. The 'doesn't work on hosted' reason is also wrong — it's not about LOCAL_AGENT_HTTP_URL, it's that the hosted Netlify demo has no writable local backend at all. Fixed both. 3. #6198 / README:159 — I documented the Settings → API Keys → Manage Keys flow as the recommended way to add OpenAI/Claude/ Gemini keys. Verified against pkg/agent/server_operations.go:288: the agent's /settings/keys endpoint literally returns an empty providers list (`providers := []providerDef{}`). The comment in the source explains 'API-key-driven agents are hidden because they cannot execute commands.' So the modal renders zero providers and the documented flow does not work in the current build. Rewrote the AI section to lead with the env-var path (which actually works), and added a note explaining why the Settings UI modal is currently empty so users don't go hunting for a feature that's been intentionally disabled. Note: #6196's other two items (Go 1.24 → 1.25 in the Linux example, and missing `mkdir -p bin`) were already addressed in PR #6197 in a different code path; verified those are still correct on main. Closes #6196, closes #6198. Signed-off-by: Andrew Anderson <[email protected]>
clubanderson
added a commit
that referenced
this pull request
Apr 10, 2026
…rs, software-properties-common (#6196, #6198) (#6207) Three Copilot review nits across two PRs, all verified against source: 1. #6196 / README:78 — sudo add-apt-repository assumes software-properties-common is installed, but minimal Ubuntu/WSL images don't ship with it. Added an explicit apt-get install line for software-properties-common, plus -y to add-apt-repository so the whole snippet runs unattended. 2. #6198 / README:102 — I claimed the GitHub PAT in the Settings UI is 'Saved by the local kc-agent to its on-disk settings file'. Wrong. Verified against web/src/components/settings/sections/GitHubTokenSection.tsx:57+ and pkg/api/server.go:692-694: GitHubTokenSection POSTs to /api/github/token, which is handled by the **console backend** (pkg/api/handlers/github_proxy.go), NOT by kc-agent. The token is persisted to ~/.kc/settings.json by the backend's settings manager. The 'doesn't work on hosted' reason is also wrong — it's not about LOCAL_AGENT_HTTP_URL, it's that the hosted Netlify demo has no writable local backend at all. Fixed both. 3. #6198 / README:159 — I documented the Settings → API Keys → Manage Keys flow as the recommended way to add OpenAI/Claude/ Gemini keys. Verified against pkg/agent/server_operations.go:288: the agent's /settings/keys endpoint literally returns an empty providers list (`providers := []providerDef{}`). The comment in the source explains 'API-key-driven agents are hidden because they cannot execute commands.' So the modal renders zero providers and the documented flow does not work in the current build. Rewrote the AI section to lead with the env-var path (which actually works), and added a note explaining why the Settings UI modal is currently empty so users don't go hunting for a feature that's been intentionally disabled. Note: #6196's other two items (Go 1.24 → 1.25 in the Linux example, and missing `mkdir -p bin`) were already addressed in PR #6197 in a different code path; verified those are still correct on main. Closes #6196, closes #6198. 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
Six factual corrections from the Copilot review of #6193, all verified against source before changing:
web/src/lib/constants/network.ts—LOCAL_AGENT_HTTP_URL = _isNetlify ? '' : 'http://127.0.0.1:8585', and_isNetlifyexplicitly includesconsole.kubestellar.iogo.moddeclaresgo 1.25.0mkdir -p binadded beforego build -o bin/kc-agentso a fresh clone doesn't failweb/src/components/agent/APIKeySettings.tsx(POSTs toKC_AGENT_URL/settings/keys)pkg/api/handlers/feedback.go:71,127LOCAL_AGENT_HTTP_URL, which is empty on Netlify. Rewrote so step 1 is 'self-host first'.pkg/agent/config.gofor env var namesCloses #6195.