Overview
Feature matrix, quick-start commands, and a high-level map of the entire project.
Welcome to the Podscape documentation. This folder contains detailed technical guides and architectural overviews for the project.
Contents
- Architecture Overview — Three-process model, Go sidecar internals, provider detection, data flow, and startup sequence.
- API Reference (Sidecar) — All HTTP endpoints exposed by the Go sidecar on
localhost:5050. - Security Hub — Dynamic image scanning (Trivy), static config audit (Kubesec), and Security Hub UI.
- Development Guide — Setup, build, test, and distribution instructions.
- Features Guide — Command palette, production context protection, unified logs, connectivity tester, pod diagnostics, kubectl plugins, and auto-updater.
- MCP Server — Install
podscape-mcp, configure Claude/Cursor, and reference for all 37 tools. - Keyboard Shortcuts — All shortcuts and the complete command palette section index.
- Troubleshooting — Sidecar issues, RBAC denied sections, build fixes, and recovery procedures.
Navigation
Press ⌘K (macOS) or Ctrl+K (Windows/Linux) to open the command palette — search any resource type, panel, or section by name.
Full keyboard shortcut reference: Keyboard Shortcuts
Quick Start
1# 1. Install Node dependencies
2npm install
3
4# 2. Build the Go sidecar (required before first dev run)
5cd go-core && go build ./cmd/podscape-core/ && cd ..
6
7# 3. Start in dev mode with hot reload
8npm run devFeature Overview
| Feature | Description |
|---|---|
| Resource Browser | 28 built-in Kubernetes resource types with live informer-backed cache |
| RBAC-aware startup | Concurrent SelfSubjectAccessReview probe at startup; denied sections show an "Access denied" banner instead of errors |
| Modular Architecture | Refactored renderer shell (Layout/Router/Overlay) and granular type system for better maintainability |
| Go Sidecar | Standalone podscape-core binary — HTTP server split across 16 handler files, shared informer cache, RBAC probe, and centralized resource metadata (k8sutil) |
| Service Mesh Support | Istio, Traefik v2/v3, NGINX Inc, NGINX Community — auto-detected per cluster via API group discovery |
| HPA v2 Metrics | Full autoscaling/v2 metric display: resource, container-resource, Pods, External targets vs current |
| CronJobs | Manual trigger support (instantiate Job from CronJob) and recent job history |
| Prometheus Charts | CPU, memory, and network time-series charts in Pod / Node / Deployment detail panels |
| Helm Management | List releases, inspect values, view history, rollback, and browse/install from Helm repositories; connection retry logic |
| Security Hub | Kubesec config audit + Trivy image CVE scanner; config/CVE split panels, kind badges, background scan with system notification, pod deduplication; export as CSV / JSON |
| Port Forwarding | One-click tunnel setup with auto port detection and live status |
| Container Shell | PTY exec-into-container via xterm.js |
| Log Streaming | Real-time WebSocket log streaming with search and fullscreen mode |
| Network Topology | Force-directed graph of pod-to-service relationships with cross-namespace connectivity testing |
| TLS Dashboard | Cluster-wide certificate inventory with expiry tracking |
| GitOps Panel | Argo CD / Flux resource overview |
| Debug Pod | Launch an ephemeral debug container on any node |
| Node Ops | Cordon, uncordon, and drain nodes with safety checks |
| Owner Chain | Interactive tree visualization showing ancestor and descendant resources |
| MCP Server | podscape-mcp — expose your cluster as tools for AI assistants (Claude, Cursor, etc.) |
| Kubeconfig Onboarding | Guided setup when no kubeconfig is detected on first launch |
| Command Palette | Cmd+K / Ctrl+K fuzzy search across all 50+ sections and resources |
| Production Context Protection | Red border + banner when connected to a context marked as production in Settings |
| Unified Log Streaming | Aggregate real-time logs from multiple pods simultaneously with per-pod color coding and search |
| Connectivity Tester | Pod-to-pod / pod-to-service network diagnostics with curl, netcat, and ping; automated DNS→TCP→HTTP flow |
| Auto-Updater | In-app update checks with download progress and one-click install |
| Kubectl Plugin Panel | Curated kubectl plugins (via Krew) with dedicated UIs — install, run, and view output without leaving the app |
| Panel Toggles | Enable or disable Plugins, GitOps, and Network panels from Settings — sidebar updates immediately |
Architecture
Three-process model (Renderer · Go Sidecar · Main), Zustand store slices, RBAC probe, sidecar lifecycle, provider detection, and the full data-flow diagram.
Podscape is a three-process Electron application. Each process has a strictly defined responsibility.
Process Layout
Renderer (React / TypeScript)
├── HTTP fetch ──────────────────► Go Sidecar (127.0.0.1:5050)
│ All Kubernetes + Helm operations
└── IPC via contextBridge ────────► Main Process (Node.js)
Terminal, settings, file dialogs,
log streaming, port-forward, sidecar lifecycle
Renderer (src/renderer/)
- Built with Vite + React + TypeScript + Tailwind CSS.
- State managed by a single Zustand store (
useAppStore) split into seven specialized slices. To prevent race conditions from rapid context switches (e.g., A → B → A), asynchronous state updates verify a monotonic sequence counter (mySeq === currentSeq) before committing results.
| Slice | Responsibility |
|---|---|
clusterSlice | Context/namespace selection, RBAC denied tracking, provider detection trigger; on context switch clears inFlightSections and evicts the Go Prometheus cache |
navigationSlice | Active section, theme, sidebar width, search state, tour state (showTour), panel toggles (pluginsEnabled, gitopsEnabled, networkEnabled), unified log pod selection (unifiedLogsSelectedPods) |
resourceSlice | All 28 resource arrays, section loading with 30s TTL + module-level inFlightSections deduplication guard, dashboard fetch, resource navigation |
operationSlice | Scale/delete/YAML modals, exec session management, port-forward state |
analysisSlice | Security scanning (kubesec + trivy), scanInBackground state for background scans, owner chain, debug pods, Prometheus config |
providersSlice | Istio/Traefik/NGINX provider detection state |
krewSlice | Krew availability detection, curated plugin index (installed status), install/uninstall actions |
- Component Orchestration: The root
App.tsxacts as a high-level shell. UI complexity is delegated to:
| Component | Responsibility |
|---|---|
Layout | Structural shell (Sidebar, Production banners, Sidecar alerts) |
SectionRouter | Routing between sections via two module-level dispatch maps (DIRECT_PANELS, LAZY_PANELS) keyed by ResourceKind; provider sections resolved via PROVIDER_SECTIONS set from config.ts |
OverlayManager | Floating terminals, YAML editors, and global modals |
ErrorBoundary | Declarative error recovery for critical UI zones |
- Talks to the sidecar via plain
fetch()through IPC helpers (checkedSidecarFetchinsrc/main/sidecar/api.ts).
Go Sidecar (go-core/)
The sidecar is a standalone HTTP server compiled as podscape-core. It is the source of truth for all Kubernetes and Helm data.
| Package | Responsibility |
|---|---|
cmd/podscape-core/main.go | Route registration, startup, token auth middleware, CORS |
internal/handlers/ | HTTP handlers split across 12 files: resources.go (resource listers), operations.go (scale/delete/rollout), helm.go, security.go, network.go, tls.go, gitops.go, prometheus.go, ownerchain.go, customresource.go, providers.go; handlers.go holds the MakeHandler RBAC factory and shared helpers. operations.go exposes dynDelete/dynGet private helpers that resolve GVRs via k8sutil and automatically retry with KindGVRFallback on NotFound (e.g. HPA autoscaling/v2 → v1 on pre-1.23 clusters). |
internal/k8sutil/ | Canonical Kubernetes metadata: KindGVR (kind → GVR), KindGVRFallback (preferred version → older fallback, e.g. HPA autoscaling/v2 → v1), ClusterScopedKinds |
internal/client/ | Shared Kubernetes client initialisation (ClientBundle: REST config, clientset, apiextensions client) |
internal/informers/ | K8s shared informers — cache resource lists in-memory for fast reads; skips informers for denied resources |
internal/store/ | ClusterStore singleton: per-context ContextCache pool, active context pointer |
internal/rbac/ | CheckAccess — concurrent SelfSubjectAccessReview probe (list + watch, 8-goroutine pool); AllResources descriptor table |
internal/ops/ | Write operations shared between sidecar and MCP server: ListResource, GetResource, Scale, Delete, RolloutRestart, RolloutUndo, ApplyYAML. GVR resolution delegates to k8sutil — Delete retries with KindGVRFallback on NotFound. |
internal/portforward/ | Manages active tunnels, streams events over WebSocket |
internal/exec/ | WebSocket-based container exec (PTY) |
internal/logs/ | WebSocket-based log streaming |
internal/ownerchain/ | Upward + downward owner reference traversal with 30s reverse-index TTL |
internal/prometheus/ | Prometheus auto-discovery via k8s service proxy; batch query with 60s TTL result cache + singleflight deduplication; atomic generation counter in ClearCache() prevents cross-context cache poisoning after context switch |
internal/helm/ | HelmRepoManager — repo list, chart search, version fetch, values, SSE install |
internal/topology/ | Cluster network topology graph (nodes → pods → services) |
internal/providers/ | Provider detection logic (Istio, Traefik, NGINX) used by the /providers endpoint |
Context cache pool: each Kubernetes context gets its own ContextCache (clientset, informers, resource maps). Switching context restarts informers for the new context without affecting others already cached.
No-kubeconfig mode: if no valid kubeconfig is found at startup, the sidecar still starts the HTTP server and sets NoKubeconfig = true. /health returns 200 immediately so the renderer can show the KubeConfigOnboarding screen instead of an error dialog. After the user sets a kubeconfig path, the sidecar is restarted via window.sidecar.restart() IPC.
Token auth: the sidecar is launched with a randomly generated token, passed via the PODSCAPE_TOKEN environment variable (not a flag — process arguments are world-readable via ps). Every request (except /health) must include the X-Podscape-Token header matching that token. The token is passed to the renderer via IPC and injected by checkedSidecarFetch.
RBAC probe: at startup and on every context switch, rbac.CheckAccess fires concurrent SelfSubjectAccessReview requests for all 28 tracked resource types checking both list and watch verbs. Results are stored in ContextCache.AllowedResources map[string]bool:
| Value | Meaning |
|---|---|
nil | Probe not yet run or failed — all resources treated as allowed (permissive) |
empty map {} | All resources denied |
| populated map | Probed result; false = denied for that resource |
Informers only register for resources where allowed[resource] != false. Each MakeHandler-built HTTP handler checks AllowedResources before serving; denied resources return 200 [] + X-Podscape-Denied: true. The renderer getResources IPC handler detects this header and throws RBACDeniedError, which loadSection catches to populate deniedSections: Set<ResourceKind> in the Zustand store. ResourceList renders an amber "Access denied" banner for denied sections instead of the generic empty state.
Sidecar Lifecycle & Crash Recovery
The sidecar subprocess is managed by src/main/sidecar/sidecar.ts. Several mechanisms work together to prevent false error dialogs and surface genuine crashes correctly.
shuttingDown flag: stopSidecar() sets shuttingDown = true before sending SIGTERM. The startup promise's exitHandler checks this flag: if the process exits while shuttingDown is true it calls resolve() (not reject()), so the caller never sees a "sidecar failed to start" error dialog during normal quit.
Crash detection after startup: once startSidecar() resolves (i.e. /health returned 200 and startupComplete is set to true), a subsequent unexpected exit event on the child process sends a sidecar:crashed IPC message to the renderer. stopSidecar() resets startupComplete = false before stopping so an intentional stop does not trigger this notification.
isQuitting guard in index.ts: a module-level isQuitting flag is set in the before-quit handler. The catch block that wraps startSidecar() checks if (isQuitting) return before showing the error dialog — a second line of defence in case the shuttingDown flag race is lost.
Renderer crash recovery: Layout.tsx (via OverlayManager and NavigationSlice) listens for sidecar:crashed via window.sidecar.onCrashed(). When fired, it shows a red banner with a "Reconnect" button. Clicking the button calls window.sidecar.restart() (IPC channel sidecar:restart), which re-runs startSidecar() in the main process, and then reloads the renderer window.
| API | Channel | Direction |
|---|---|---|
window.sidecar.onCrashed(cb) | sidecar:crashed | Main → Renderer |
window.sidecar.restart() | sidecar:restart | Renderer → Main |
Main Process (src/main/)
| File | Responsibility |
|---|---|
index.ts | App bootstrap, splash window, sidecar start, BrowserWindow creation |
sidecar/sidecar.ts | Launch / monitor / kill the Go subprocess; expose sidecar:restart IPC |
sidecar/api.ts | checkedSidecarFetch — injects token, retries up to 20× with 500 ms delay |
sidecar/auth.ts | Generates the random per-session X-Podscape-Token |
sidecar/runtime.ts | Shared activeSidecarPort variable |
ipc/kubectl.ts | IPC handlers for log streaming, port-forward, file copy, owner chain, metrics |
ipc/terminal.ts | PTY terminal sessions via node-pty |
ipc/helm.ts | Helm IPC handlers — repo browser, SSE install relay |
ipc/settings.ts | Settings IPC handlers |
ipc/dialog.ts | Native file open/save dialogs |
settings/settings_storage.ts | Read / write ~/.podscape/settings.json |
system/env.ts | Augments subprocess PATH for cloud credential helpers |
system/updater.ts | Auto-updater checks and notifications |
system/kubeProvider.ts | Kubeconfig path resolution |
Production Context Tracking
Podscape lets operators mark specific context names as "production" to guard against accidental changes.
Store fields (in clusterSlice, src/renderer/store/slices/clusterSlice.ts):
| Field | Type | Description |
|---|---|---|
prodContexts | string[] | List of context names treated as production |
isProduction | boolean | Derived: true when selectedContext is included in prodContexts |
setProdContexts(contexts) | async action | Updates both the store and ~/.podscape/settings.json atomically |
isProduction is recomputed whenever selectContext runs or setProdContexts is called — there is no selector subscription overhead.
Visual indicators (managed in src/renderer/components/core/Layout.tsx):
- Red ring: the root
<div>gainsring-inset ring-4 ring-red-500/50whenisProductionis true. - Production banner: a fixed, centered banner reading "PRODUCTION CONTEXT ACTIVE" at z-index 10000.
Persistence: prodContexts is stored in ~/.podscape/settings.json under the prodContexts key (an array of strings). On app launch, settings_storage.ts merges saved settings over defaults before the renderer hydrates the store.
Preload (src/preload/index.ts)
Exposes six namespaced APIs to the renderer via contextBridge:
| Namespace | Purpose |
|---|---|
window.kubectl | All k8s operations, port-forward, log streaming, file copy, owner chain, Prometheus queries + prometheusFlushCache |
window.helm | Helm release operations and repo browser |
window.exec | PTY exec-into-container sessions |
window.settings | Read / write app settings |
window.kubeconfig | Kubeconfig file path selection |
window.dialog | Native file open/save dialogs |
window.sidecar | Sidecar restart (used by kubeconfig onboarding) |
Provider Detection (Istio / Traefik / NGINX)
On every successful context switch the renderer fires fetchProviders() against the sidecar's /providers endpoint. The sidecar uses the Kubernetes discovery API and IngressClass controller fields to detect installed service meshes and ingress controllers:
| Provider | Detection method |
|---|---|
| Istio | networking.istio.io API group present |
| Traefik v3 | traefik.io API group present |
| Traefik v2 | traefik.containo.us API group present |
| NGINX Inc | k8s.nginx.org API group present |
| NGINX Community | IngressClass controller field contains ingress-nginx |
The providers value in the Zustand store drives conditional sidebar groups. fetchProviders captures the context at call time and discards results if the context changed while the request was in-flight (stale-context guard). On context switch, all provider flags reset to false and any active provider section (member of PROVIDER_SECTIONS in src/renderer/config.ts) auto-navigates to dashboard to prevent stale CRD fetches.
MCP Server (podscape-mcp)
podscape-mcp is a standalone binary built from go-core/cmd/podscape-mcp/. It exposes the Kubernetes cluster as MCP (Model Context Protocol) tools for AI assistants such as Claude and Cursor. It is independent of the Electron app and can be run directly from the command line.
It reuses the internal/client, internal/ops, and internal/helm packages from the sidecar to avoid duplicating Kubernetes client logic.
Startup Sequence
1. app.whenReady()
2. createSplashWindow() ← frameless Kubernetes-animated splash
3. startSidecar() ← spawns podscape-core, polls /health every 500ms
├─ if kubeconfig missing:
│ sidecar enters no-kubeconfig mode → /health returns 200 immediately
└─ if kubeconfig found:
a. HTTP server starts (binds to 127.0.0.1:<port>)
b. rbac.CheckAccess — concurrent SAR probe, 10s deadline
→ writes AllowedResources into initial ContextCache
c. informers.InitInformers — only registers informers for allowed resources
d. ContextCache.HasData = true → /health returns 200
4. createWindow(onReady)
└─ ready-to-show → splash.destroy(), main window shown
Architecture Diagram
Application Security
Electron hardening
| Setting | Value | Effect |
|---|---|---|
nodeIntegration | false | Renderer cannot access Node.js APIs |
contextIsolation | true | Preload and renderer run in separate JS contexts |
sandbox | true | Renderer process is OS-sandboxed |
setWindowOpenHandler | deny + openExternal | New window requests are blocked; links open in the system browser instead |
Sidecar token auth
At startup, sidecar/auth.ts generates a random 64-character hex token (crypto.randomBytes(32)). It is passed to the sidecar in the PODSCAPE_TOKEN environment variable, which the sidecar unsets immediately after reading so nothing it spawns inherits it, and injected into every HTTP request by checkedSidecarFetch as the X-Podscape-Token header. The sidecar rejects any request (except /health) that omits or mismatches the token. The token is never written to disk and is unique per app session.
Secret masking
The bulk /secrets endpoint returns only key names — values are replaced server-side before the response leaves the sidecar. A value is only transmitted when the user explicitly clicks "Reveal" for a specific key, which calls the /secret/value?name=&namespace=&key= endpoint.
Path traversal protection
sanitizeCPToLocalPath in go-core/internal/handlers/operations.go validates every local path used by the file-copy (/cp/to, /cp/from) endpoints. It resolves the input with filepath.Abs + filepath.EvalSymlinks (following all symlinks) before confirming the real path starts within the user's home directory or the OS temp directory. Absolute paths from the native file dialog are accepted; only paths that escape the allowed roots are rejected.
Dependency security pins
package.json overrides pins transitive dependencies that have known CVEs to safe versions:
| Package | Reason |
|---|---|
dompurify ≥ 3.4.0 | mXSS, prototype pollution, ADD_ATTR bypass fixes |
@xmldom/xmldom ^0.8.12 | XML parser security fixes |
lodash ^4.18.1 | Prototype pollution |
brace-expansion ^1.1.13 / ^2.0.3 | ReDoS |
RBAC
The sidecar runs SelfSubjectAccessReview against all 28 tracked resource types at startup and on every context switch. Resources the current user cannot list or watch return 200 [] with X-Podscape-Denied: true — the renderer shows an "Access denied" banner rather than an error. No data from denied resources ever reaches the renderer.
Namespace-Scoped Fallback (OR-logic):
For users on multi-tenant clusters scoped with RoleBindings rather than cluster-wide ClusterRoleBindings, a cluster-scoped SAR check (namespace "") is rejected. To prevent false negatives:
- When a namespace-scoped resource fails the cluster-scoped check, the RBAC probe retries the SAR check specifically in the
"default"namespace. - Access is granted if either check passes (OR-logic).
- Cluster-scoped resources (like
Nodes,Namespaces,PersistentVolumes) bypass the"default"namespace check.
Ephemeral Port Forwarding (TOCTOU Prevention)
Programmatic port forwarding previously searched for a free local port using freeLocalPort() and then bound it. This left a Time-of-Check to Time-of-Use (TOCTOU) window where another process could grab the port.
To eliminate this vulnerability:
- The Go sidecar binds port
0(e.g.,127.0.0.1:0), instructing the operating system to allocate a free ephemeral port atomically. - Once the tunnel is successfully established, the sidecar retrieves the allocated port via
pf.GetPorts()and returns it to the client.
Helm Downloader Protections
To protect the sidecar from memory exhaustion (Denial of Service) and hanging network calls when downloading Helm repository assets (such as massive index.yaml files or chart values):
- Body Limit: A strict limit of 64MB is enforced on all HTTP response bodies read when downloading Helm repository indexes or configuration files.
- Network Timeouts: A strict timeout of 60 seconds is applied to all outgoing HTTP connection and read phases during Helm downloads.
WebSocket Thread Safety
Gorilla WebSocket (github.com/gorilla/websocket) does not allow concurrent write operations or concurrent read operations on the same connection.
- Writes: Outgoing WebSocket frames are serialized using a
sync.Mutexinside thewsStream.Writehelper. - Reads: A single read-pump goroutine is established to read incoming frames from the WebSocket and write them to an
io.Pipe. The execution handler (exec.Exec) reads stdin from the other end of the pipe, preventing concurrent read conflicts.
Key Constants
All renderer-to-sidecar fetch calls use constants from src/common/constants.ts:
SIDECAR_HOST = '127.0.0.1'
SIDECAR_PORT = 5050
SIDECAR_BASE_URL = 'http://127.0.0.1:5050'
SIDECAR_WS_URL = 'ws://127.0.0.1:5050'Features Guide
Deep-dives into command palette, production-context protection, unified log streaming, connectivity tester, pod diagnostics, CRD browser, and the auto-updater.
This guide covers features that go beyond basic resource browsing. Each section explains what the feature does, when to use it, and how to operate it.
Command Palette
The Command Palette gives you instant access to every section and every loaded resource in your cluster without touching the sidebar.
Opening and closing
| Platform | Shortcut |
|---|---|
| macOS | ⌘K |
| Windows / Linux | Ctrl+K |
Press the same shortcut again, or press Escape, to dismiss the palette.
How to use it
Start typing as soon as the palette opens. Results appear in two groups:
- Sections — up to 5 matching navigation destinations (Dashboard, Pods, Security Hub, Connectivity, etc.)
- Resources — up to 12 matching Kubernetes objects by name, drawn from all 27+ resource types that are currently loaded in the store
Use ↑ and ↓ to move between results, then press ↵ to navigate. Selecting a resource result navigates directly to that resource's detail view, automatically switching the namespace and section for you.
What is searchable
The palette searches across:
- All section names and their aliases (e.g. searching
"batch"surfaces Jobs and CronJobs;"rbac"surfaces Roles, ClusterRoles, RoleBindings, and ClusterRoleBindings) - The
sectionidentifier itself (e.g."unifiedlogs") - The
.metadata.namefield of every loaded resource across all 27 resource types
Example queries
| Query | What it finds |
|---|---|
nginx-api | Any pod, deployment, or service whose name contains nginx-api |
batch | Navigates to Jobs or CronJobs sections |
scan | Navigates to Security Hub |
cert | Navigates to TLS Certificates |
ping | Navigates to Connectivity Tester |
my-postgres | Opens the detail view for the my-postgres StatefulSet (or pod, or service) directly |
When to use it
The Command Palette is most useful when you already know the name of the resource you want to inspect, or when you need to jump between sections quickly without scrolling the sidebar. It is the fastest path from any screen to any resource.
Production Context Protection
Accidentally running a destructive operation against a production cluster is a serious risk. Production Context Protection adds a persistent visual warning whenever you are connected to a cluster you have marked as production.
What it looks like
When the active context is a production context, Podscape shows two simultaneous indicators:
- A red "PRODUCTION CONTEXT ACTIVE" banner drops down from the top-center of the window.
- A 4px red inset ring appears around the entire application frame, making it visually unmistakable even when the banner is outside your line of sight.
Both indicators are active for the entire session — they do not auto-dismiss.
How to configure it
- Open Settings (sidebar, bottom of the left navigation, or search
"settings"in the Command Palette). - Find the Production Contexts field.
- Enter the names of your production kubeconfig contexts, one per line or comma-separated.
- Save. The setting is stored in
~/.podscape/settings.jsonunder theprodContextskey and persists across restarts.
The check is performed whenever you switch contexts. If the newly selected context is in your prodContexts list, the indicators activate immediately and stay active until you switch to a non-production context.
Why it is useful
The visual indicators serve as a last line of defence before you scale a deployment down to zero, delete a namespace, or drain a node. Unlike role-based access controls that live in the cluster, this protection is client-side and requires no cluster permissions to configure.
Unified Log Streaming
Unified Log Streaming lets you watch the live output of multiple pods side by side in a single, color-coded terminal view. It is the fastest way to correlate log lines across replicas or co-dependent services.
Opening the panel
Navigate to Unified Logs in the sidebar, or search "unified" in the Command Palette (⌘K / Ctrl+K).
Adding pods to the stream
- Type a pod name or namespace into the "Add pods to stream..." search field in the top-right of the panel. The field autocompletes against all Running pods in your selected namespace.
- Click a pod in the dropdown to add it to the active stream list. You can add as many pods as you need.
- Added pods appear as dismissible pills in the Streams row below the toolbar.
Only Running pods are shown in the picker. Pods that terminate while streaming are automatically removed from the selection.
Starting and stopping
Click Start Stream to begin streaming. Podscape opens a live WebSocket log stream for the first container in each selected pod simultaneously. The button changes to Stop All while streaming is active.
You cannot add or remove pods while a stream is running. Stop the stream first, adjust the selection, then restart.
Color coding
Each pod is assigned a distinct color from a fixed palette (blue, green, rose, amber, purple, cyan, orange, pink). The pod name column in the log output uses this color, making it easy to visually separate log lines from different sources at a glance.
Searching and filtering
A Filter Log Output bar sits at the bottom of the terminal area. Type any string to filter the displayed log lines in real time — only lines whose message or pod name contains the search term are shown. Matching text is highlighted inline with a blue background. The filter does not affect the underlying stream; remove the search term to see all lines again.
The panel retains at most 1,000 log lines in memory. Older lines are discarded as new ones arrive.
Auto-scroll
The Auto toggle button in the toolbar controls whether the log view automatically scrolls to the bottom as new lines arrive. Auto-scroll is on by default. Click the button to pause at your current scroll position (useful when reviewing older output); click it again to resume following the live tail.
Use the trash icon button to clear all buffered log lines without stopping the stream.
Context switching
Switching to a different kubeconfig context automatically stops all active streams and clears the pod selection and log buffer. This prevents stale log data from a previous cluster appearing after a context switch.
Connectivity Tester
The Connectivity Tester lets you verify network reachability between pods inside your cluster without leaving Podscape. It runs diagnostic commands inside a source pod using kubectl exec, so no external tooling is required.
Navigate to Connectivity in the sidebar (under the Tools group), or search "connectivity" in the Command Palette.
Two modes
| Mode | When to use |
|---|---|
| Diagnose | Automated step-by-step DNS → TCP → HTTP test between a source pod and a target service or pod |
| Manual | Run a single arbitrary command (curl, nc, or ping) from a source pod to any target |
Switch between modes using the Diagnose / Manual toggle at the top of the panel.
Diagnose mode
Diagnose mode walks through three steps in sequence:
- DNS Resolution — runs
nslookupagainst the target hostname inside the source pod to verify the cluster DNS can resolve the name. - TCP Port Check — runs
nc -zvto confirm the target's TCP port is reachable. - HTTP Response — runs
curlwith a 10-second timeout and reports the HTTP status code and total response time.
If the DNS step fails, the TCP and HTTP steps are automatically skipped (they would fail for the same reason). Each step reports its result and duration in milliseconds, and you can expand an Output section to see the raw command output.
Failure Analysis — if any step fails, an "Investigate Failure" button appears. Clicking it fetches the relevant NetworkPolicies and Endpoint objects from the cluster and displays:
- Ingress NetworkPolicies in the target namespace — including which pods they select and whether they are a deny-all policy.
- Egress NetworkPolicies on the source pod — to identify outbound traffic restrictions.
- Endpoint readiness for the target service — showing how many pods are ready and their names.
This analysis saves the manual work of cross-referencing kubectl get netpol output with endpoint state when tracking down connectivity failures.
Example diagnostic workflow:
- Select Source pod:
frontend-abc123(namespace:prod) - Set Target:
api-service.prod.svc.cluster.local, port8080, path/health - Click Run Diagnosis
- Step 1 (DNS) passes in 12ms. Step 2 (TCP) fails after 5000ms.
- Click Investigate Failure — the analysis shows a NetworkPolicy
deny-external-ingressin theprodnamespace that selects all pods and denies all ingress with no rules defined. This is the cause of the TCP failure.
Manual mode
Manual mode gives you direct access to three commands:
| Command | Use case |
|---|---|
curl | Test HTTP/HTTPS endpoints, check response codes, inspect headers |
nc | Check raw TCP port reachability |
ping | Verify basic IP-level connectivity and measure round-trip time |
Select the source pod, enter the host, port, and optional path, choose a protocol, and click Run. The raw output and exit code are displayed inline. The run history is preserved in the panel so you can compare results across multiple tests.
How targets are specified
- Service DNS names are auto-completed from the list of services in your cluster. Selecting a service fills in the canonical cluster DNS name (e.g.
my-svc.my-namespace.svc.cluster.local). - Pod DNS names are derived from the pod's IP address using the stable pod DNS format (
<ip-dashes>.<namespace>.pod.cluster.local). - You can also type any hostname or IP address manually.
CronJob Manual Triggering
You can manually instantiate a Job from a CronJob at any time, bypassing the schedule. This is useful for testing CronJobs or running unscheduled maintenance tasks.
- Navigate to the CronJobs section.
- Open a CronJob detail view.
- Click the Trigger Now button in the toolbar.
A new Job reflects the CronJob's template and is tracked in the Recent Jobs history table within the CronJob detail view.
Helm Release Management
Podscape provides a premium interface for managing Helm releases, including automated update detection and a streamlined upgrade workflow.
Update Detection
Whenever you open a Helm release detail view, Podscape automatically searches your configured repositories for newer versions of the chart.
| Status | Meaning |
|---|---|
| Update available | A newer version was found in a configured repository. A glowing blue badge shows the version number. |
| Latest version | Your release is already running the most recent version available in the repos. |
| Local / Custom Chart | The chart was installed from a local path or a source not found in your repositories. Update checking is skipped for these resources. |
Direct Upgrades
If an update is available, an Upgrade button appears in the release metadata.
- Clicking Upgrade fetches your current configuration values.
- A YAML editor opens, pre-filled with your existing overrides.
- After reviewing or modifying the values, click Save & Upgrade to perform a cross-version upgrade.
This flow ensures that your production overrides are never lost during a chart version bump.
Pod Diagnostics
Pod Diagnostics provides automated crash analysis and a chronological event timeline directly inside the Pod detail panel. Open any pod from the Pods section, then select the Diagnostics tab.
Restart Analyzer
The Restart Analyzer inspects the pod's container statuses and correlated events to produce a human-readable diagnostic summary. It checks for:
| Condition | What it means |
|---|---|
| OOMKilled | The container was terminated by the Linux kernel because it exceeded its configured memory limit. The analyzer flags this with a red "Memory Limit Exceeded" card and recommends increasing resource limits. |
| Non-zero exit code | The application process crashed. The analyzer shows a "Application Crash" warning card with the exit code and advises checking application logs for stack traces. |
| Unhealthy probe events | Liveness or readiness probe failures that caused a restart. The analyzer surfaces the probe failure message from the cluster event stream. |
| CrashLoopBackOff | The pod is restarting repeatedly and Kubernetes is applying exponential backoff. Shown as a red error card. |
If none of these conditions are found, the analyzer shows a green "Everything looks stable!" indicator.
Below the diagnostic summary, the Last Termination States section shows a per-container breakdown of the last recorded termination: reason, exit code, timestamp, and any termination message from the container runtime.
Lifecycle Timeline
The Lifecycle Timeline renders a chronological vertical timeline of every significant event in the pod's life, from creation to the current moment. Each entry includes:
- A color-coded dot: green (success), amber (warning), red (error), blue (info)
- The event title and a human-readable message
- A relative timestamp ("3m ago")
- A repeat count badge if the same event occurred multiple times
- A pulsing LIVE badge on the current state when the pod is still active
The timeline combines data from the pod's own status conditions (Scheduled, Initialized, ContainersReady, Ready) with events fetched from the Kubernetes event stream for that pod. This gives you the complete picture of what happened during a pod's startup sequence or after a failure — without running kubectl describe pod.
When to use Pod Diagnostics
- A pod is restarting repeatedly and you need to determine whether it is OOM, a probe failure, or an application crash.
- A pod is stuck in
PendingorCrashLoopBackOffand you want to understand the sequence of events that led to the current state. - You are reviewing the startup sequence of a newly deployed pod to confirm all readiness gates passed in the expected order.
CRD Browser
The CRD Browser lets you explore and edit instances of any Custom Resource Definition installed in your cluster — without writing any kubectl commands.
Opening a CRD
Navigate to Cluster → CRDs in the sidebar. The table lists every CRD in the cluster with its group, scope (Namespaced / Cluster), and instance count. Click any row to open the full-page CRD detail view.
The detail page replaces the main content area and shows:
- A header with the CRD kind, API group, plural name, full name, scope badge, and live instance count.
- A Definition YAML button to view and edit the CRD's own schema manifest.
- A
← CRDsbreadcrumb at the top left to return to the list.
Browsing instances
Below the header, a resizable list + detail split shows all instances of that CRD. The list columns are:
| Column | Notes |
|---|---|
| Name | Resource name in monospace |
| Namespace | Shown only when viewing all namespaces |
| Age | Time since creation |
Click an instance row to open its detail panel on the right. Drag the divider between the list and the detail panel to resize them. Clicking the selected row again closes the panel.
Instance detail tabs
Each instance has three tabs:
Metadata — Name, namespace, API version, kind, creation timestamp, labels (as pill badges), and annotations.
Spec — The full spec rendered as formatted YAML. Scroll to read; no interaction required.
YAML Edit — The complete resource manifest in an editor. Make changes and click Apply to apply them to the cluster via server-side apply.
Provider CRD sections (Istio / Traefik / NGINX)
When Istio, Traefik v2/v3, or NGINX Inc is detected in your cluster, dedicated sidebar sections appear (e.g. Virtual Services, Ingress Routes, Virtual Servers). These use the same generic list + detail layout as the CRD Browser, with an additional Summary column showing the most relevant field at a glance:
| Section | Summary column |
|---|---|
| Virtual Services | Total HTTP + TCP route count |
| Destination Rules | Host |
| Gateways | Server count |
| Service Entries | Location (MESH_INTERNAL / MESH_EXTERNAL) |
| Peer Authentication | mTLS mode |
| IngressRoutes (Traefik) | Entry points |
| Middlewares | Type |
| Virtual Servers (NGINX) | Host |
Kubectl Plugin Panel
The Plugin Panel brings a curated set of kubectl plugins directly into Podscape. You can install, run, and view plugin output without leaving the app or touching your terminal.
Opening the panel
Navigate to Plugins in the sidebar, or search "plugins" in the Command Palette (⌘K / Ctrl+K).
Tabs
| Tab | Shows |
|---|---|
| Installed | Plugins from the curated list that are currently installed on your machine |
| Browse | All curated plugins, installed or not |
Plugins installed via
kubectl krew installthat are not in Podscape's curated list are intentionally not shown — the panel only surfaces plugins with first-class Podscape UI support.
Installing a plugin
Krew must be installed on your machine. If it is not detected, the panel shows a one-click Krew installer.
- Switch to the Browse tab.
- Click any plugin row to open its Info view.
- Click Install. Podscape runs
kubectl krew install <plugin>in the background. - Once installed, the Run tab becomes available.
Running a plugin
- Click any installed plugin row (or switch to the Run tab from the Info view).
- Fill in the inputs (namespace, resource name, etc.) and click Run.
- Output streams live into the panel — table view, YAML editor, or raw terminal depending on the plugin.
Refreshing the index
Click Refresh in the toolbar to run kubectl krew update and reload the installed plugin list. This is useful after installing plugins from the terminal or after a krew upgrade.
Curated plugins
Podscape ships with built-in UI support for the following plugins. We are grateful to their authors for building and open-sourcing these tools.
| Plugin | What it does | Author |
|---|---|---|
| neat | Strips managed fields and defaults from manifests to make them human-readable | @itaysk |
| stern | Tails logs from multiple pods simultaneously with regex filtering | stern/stern |
| tree | Visualises Kubernetes object ownership hierarchies | @ahmetb |
| images | Lists all container images running in the cluster | @chenjiandongx |
| whoami | Shows the currently authenticated subject | @rajatjindal |
| df-pv | Reports disk usage for PersistentVolumeClaims | @yashbhutwala |
| outdated | Finds container images running outdated versions | replicatedhq |
Podscape does not bundle or redistribute these plugins. They are installed and managed on your local machine via Krew.
Adding a new plugin
See the Contributing Guide for step-by-step instructions on adding a new plugin to the curated list.
Auto-Updater
Podscape checks for new releases automatically in the background using the built-in Electron auto-updater. No manual download or re-installation is required.
How update checks work
On startup, Podscape queries the GitHub Releases feed for the repository. If a newer version is available, a banner appears at the very top of the application window. The check runs once per launch; there is no periodic polling during the session.
The UpdateBanner flow
The banner progresses through three states:
1. Available (blue banner)
Podscape
<version>is available. [Download] [×]
A Download button starts the background download immediately. You can dismiss the banner with the × button and continue working; the download does not happen unless you explicitly click Download.
2. Downloading (blue banner with progress bar)
Downloading update… 47%
A progress bar fills as the update package downloads. The banner cannot be dismissed during this state.
3. Ready to install (green banner)
Podscape
<version>is ready to install. [Restart & Install]
Click Restart & Install to quit Podscape, apply the update, and relaunch. If you dismissed the "available" notice earlier, the banner re-appears automatically when the download completes — you will always see this final prompt before the install.
If the update check or download fails, an amber error banner appears with the failure reason. You can dismiss it and continue using the current version.
Supported platforms
Automatic updates are supported on macOS and Windows. Linux users receive a notification but must download and install the new package manually from the GitHub Releases page.
MCP Server
Install podscape-mcp, wire it into Claude or Cursor, and reference all 25 tools — read-only, diagnostic, and mutating.
podscape-mcp is a standalone binary that exposes your Kubernetes cluster as Model Context Protocol (MCP) tools. It lets AI assistants — Claude, Claude Code, Cursor, and any other MCP-compatible client — query and manage your cluster in plain language without requiring kubectl knowledge.
The MCP server connects directly to the Kubernetes API using your kubeconfig. It is an independent binary that runs alongside (or without) the Podscape desktop app.
Prerequisites
- A kubeconfig file with at least one context configured (default:
~/.kube/config) - Go 1.22+ if building from source, or one of the pre-built binaries from GitHub Releases
- The Podscape desktop app is not required —
podscape-mcptalks to the cluster directly
Installation
Option A — Pre-built binary (recommended)
Pre-built binaries for all platforms are published on every GitHub Release.
macOS (Apple Silicon):
sudo curl -L https://github.com/codingprotocols/podscape/releases/latest/download/podscape-mcp-darwin-arm64 \
-o /usr/local/bin/podscape-mcp && sudo chmod +x /usr/local/bin/podscape-mcp
# Clear Gatekeeper quarantine (unsigned binary)
xattr -dr com.apple.quarantine /usr/local/bin/podscape-mcpmacOS (Intel):
sudo curl -L https://github.com/codingprotocols/podscape/releases/latest/download/podscape-mcp-darwin-amd64 \
-o /usr/local/bin/podscape-mcp && sudo chmod +x /usr/local/bin/podscape-mcp
xattr -dr com.apple.quarantine /usr/local/bin/podscape-mcpLinux (amd64):
sudo curl -L https://github.com/codingprotocols/podscape/releases/latest/download/podscape-mcp-linux-amd64 \
-o /usr/local/bin/podscape-mcp && sudo chmod +x /usr/local/bin/podscape-mcpWindows (amd64): Download podscape-mcp-windows-amd64.exe from the release page and place it somewhere on your PATH.
Option B — Build from source
cd go-core
go build ./cmd/podscape-mcp/The binary is produced at go-core/podscape-mcp.
Configuring your AI assistant
The MCP server communicates over stdio and is started automatically by your MCP client — you do not run it manually.
Claude Code (CLI)
# Installed binary
claude mcp add --transport stdio podscape -- /usr/local/bin/podscape-mcp
# During development — point at the locally built binary
claude mcp add --transport stdio podscape -- $(pwd)/go-core/podscape-mcpAfter adding, start a new Claude Code session — MCP servers connect on startup:
claudeVerify the server is connected inside the new session:
/mcp
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
1{
2 "mcpServers": {
3 "podscape": {
4 "command": "/usr/local/bin/podscape-mcp",
5 "args": []
6 }
7 }
8}To use a non-default kubeconfig:
1{
2 "mcpServers": {
3 "podscape": {
4 "command": "/usr/local/bin/podscape-mcp",
5 "args": ["--kubeconfig", "/path/to/your/kubeconfig"]
6 }
7 }
8}Restart Claude Desktop after editing the config file.
Cursor
Edit .cursor/mcp.json in your project (or the global Cursor MCP config):
1{
2 "mcpServers": {
3 "podscape": {
4 "command": "podscape-mcp",
5 "args": []
6 }
7 }
8}Other MCP clients
Any MCP client that supports stdio transport works. The server name is podscape and the command is the path to the podscape-mcp binary with an optional --kubeconfig argument.
CLI flags
| Flag | Default | Description |
|---|---|---|
--kubeconfig | (see below) | Path to kubeconfig file |
Kubeconfig resolution order: --kubeconfig flag → $KUBECONFIG environment variable → ~/.kube/config.
Safety gates
Three destructive tools require an explicit confirm=true parameter to execute. Calling them without confirm=true returns a preview of what would be affected — no cluster state is changed.
| Tool | Preview shows |
|---|---|
delete_resource | Kind, name, and namespace that would be deleted |
drain_node | Exact pod list that would be evicted vs skipped (capped at 50) |
helm_uninstall | Release name and namespace that would be removed |
This two-step pattern prevents accidental deletions when an AI assistant constructs a tool call from an ambiguous instruction.
Available Tools
podscape-mcp exposes 37 tools across four categories.
Read-only tools (15)
These tools only read from the cluster and never modify state.
list_resources
List any Kubernetes resource type. Supports all built-in types and any CRD by plural name.
| Parameter | Type | Required | Description |
|---|---|---|---|
resource | string | yes | Resource type: pods, deployments, services, nodes, configmaps, secrets, custom CRD plural names (e.g. virtualservices, ingressroutes), etc. |
namespace | string | no | Namespace filter; omit for all namespaces |
label_selector | string | no | Label selector, e.g. app=nginx or env=prod,tier=frontend |
field_selector | string | no | Field selector, e.g. status.phase=Running or spec.nodeName=node-1 |
limit | number | no | Max results to return (default 100; set to 0 for unlimited) |
get_resource
Get a single Kubernetes resource by name. Supports built-in types and CRDs.
| Parameter | Type | Required | Description |
|---|---|---|---|
resource | string | yes | Resource type |
name | string | yes | Resource name |
namespace | string | no | Namespace; omit for cluster-scoped resources |
get_resource_yaml
Get the full YAML manifest of a resource. Returns the same data as get_resource but formatted as YAML, equivalent to kubectl get -o yaml.
| Parameter | Type | Required | Description |
|---|---|---|---|
resource | string | yes | Resource type |
name | string | yes | Resource name |
namespace | string | no | Namespace; omit for cluster-scoped resources |
get_pod_logs
Fetch container logs. Output is capped at 512 KB total; a truncation notice is appended if the limit is reached.
| Parameter | Type | Required | Description |
|---|---|---|---|
pod | string | yes | Pod name |
namespace | string | yes | Namespace |
container | string | no | Container name (defaults to first container) |
tail | number | no | Number of lines (default 100); ignored when since_minutes is set |
since_minutes | number | no | Return logs from the last N minutes (overrides tail) |
previous | boolean | no | Fetch logs from the previously terminated container instance (useful for crash-looping pods) |
init_container | boolean | no | When true, fetches logs from init containers instead of main containers |
list_events
List Kubernetes events sorted by most recent first.
| Parameter | Type | Required | Description |
|---|---|---|---|
namespace | string | no | Namespace filter; omit for all namespaces |
type | string | no | Warning or Normal; omit for all types |
object_name | string | no | Filter events for a specific object name |
limit | number | no | Max events to return (default 100) |
list_contexts
List all available Kubernetes contexts from the kubeconfig, and report the currently active one.
No parameters required.
Example output:
{
"contexts": ["prod-cluster", "staging-cluster", "local-kind"],
"current": "prod-cluster"
}get_current_context
Return the name of the active Kubernetes context. No parameters required.
list_namespaces
List all namespaces in the cluster. No parameters required.
helm_list
List Helm releases in the cluster.
| Parameter | Type | Required | Description |
|---|---|---|---|
namespace | string | no | Namespace filter; omit for all namespaces |
helm_status
Get the full status output of a Helm release.
| Parameter | Type | Required | Description |
|---|---|---|---|
release | string | yes | Release name |
namespace | string | yes | Namespace |
helm_values
Get the values of a Helm release.
| Parameter | Type | Required | Description |
|---|---|---|---|
release | string | yes | Release name |
namespace | string | yes | Namespace |
all | boolean | no | Include computed/default values (equivalent to helm get values --all) |
helm_history
List all revisions of a Helm release.
| Parameter | Type | Required | Description |
|---|---|---|---|
release | string | yes | Release name |
namespace | string | yes | Namespace |
Returns an array of revisions, each with revision, status, chart, appVersion, updated, and description.
security_scan
Run a security posture scan on all pods in a namespace. Checks for:
- Missing
SecurityContext - Privileged containers
- Containers running as root (container-level and pod-level)
- Missing resource limits
- Host network / PID / IPC namespace usage
allowPrivilegeEscalationnot explicitly set tofalsereadOnlyRootFilesystemnot set totrue- Dangerous capabilities present:
NET_ADMIN,SYS_ADMIN,SYS_PTRACE,ALL
| Parameter | Type | Required | Description |
|---|---|---|---|
namespace | string | yes | Namespace to scan |
Each finding includes: pod, container, issue, and severity (WARN, HIGH, or CRITICAL).
detect_providers
Detect installed ingress controllers and service mesh providers in the cluster (Istio, Traefik v2/v3, NGINX Inc, NGINX Community). Uses the Kubernetes discovery API and IngressClass controller fields.
No parameters required.
list_crds
List all CustomResourceDefinitions installed in the cluster.
| Parameter | Type | Required | Description |
|---|---|---|---|
group | string | no | Filter by API group, e.g. karpenter.sh or traefik.io |
get_metrics
Get CPU and memory usage for pods or nodes. Requires metrics-server to be installed in the cluster.
| Parameter | Type | Required | Description |
|---|---|---|---|
kind | string | yes | pods or nodes |
namespace | string | no | Namespace filter for pods; omit for all namespaces |
Diagnostic tools (5)
These tools bundle multiple API calls into a single response to reduce round-trips during common diagnostic workflows.
pod_summary
Get a combined view of a pod's status, container states, recent events, and last N log lines — everything needed to diagnose a failing pod in one call. Init container logs are fetched concurrently alongside main container logs and included in container_logs under init:<name> keys.
| Parameter | Type | Required | Description |
|---|---|---|---|
pod | string | yes | Pod name |
namespace | string | yes | Namespace |
tail | number | no | Log lines per container (default 50) |
previous | boolean | no | Fetch logs from the previously terminated container instance |
Returns: phase, conditions, containers (state/reason/message per container), events, and container_logs (map of container name → log output; init containers keyed as init:<name>).
cluster_health
Get a one-call cluster health overview: node ready/total counts, pod counts by phase (Running, Pending, Failed, etc.), and Warning events from the last hour.
No parameters required.
Warning events are capped at 50 entries; a warning_events_truncated: true field is added when the cap is reached.
list_failing_pods
List all pods that are not in Running or Succeeded state, plus any Running pods with containers in a Waiting or not-ready state. Includes phase, reason, and per-container failure details.
| Parameter | Type | Required | Description |
|---|---|---|---|
namespace | string | no | Namespace filter; omit for all namespaces |
get_resource_events
Get Kubernetes events for a specific named resource — equivalent to the Events section of kubectl describe.
| Parameter | Type | Required | Description |
|---|---|---|---|
kind | string | yes | Resource kind, e.g. Pod, Deployment, Node, Service |
name | string | yes | Resource name |
namespace | string | no | Namespace; omit for cluster-scoped resources |
describe_resource
Get a resource and its events in one call — equivalent to kubectl describe without the table formatting. Avoids requiring two separate tool calls when diagnosing a resource.
| Parameter | Type | Required | Description |
|---|---|---|---|
resource | string | yes | Resource type (plural), e.g. pods, deployments, services |
name | string | yes | Resource name |
namespace | string | no | Namespace; omit for cluster-scoped resources |
Returns: { "resource": { ... }, "events": [ ... ] }
Mutating tools (11)
These tools modify cluster state. Destructive tools require confirm=true — see Safety gates.
scale_resource
Scale a deployment or statefulset to a desired replica count.
| Parameter | Type | Required | Description |
|---|---|---|---|
kind | string | yes | deployment or statefulset |
name | string | yes | Resource name |
namespace | string | yes | Namespace |
replicas | number | yes | Desired replica count (must be >= 0) |
delete_resource
Delete a Kubernetes resource. Requires confirm=true to execute — call without it first to see a preview.
| Parameter | Type | Required | Description |
|---|---|---|---|
kind | string | yes | Resource kind, e.g. pod, deployment, service |
name | string | yes | Resource name |
namespace | string | yes | Namespace |
confirm | boolean | no | Must be true to delete. Omit or set false to preview what will be deleted. |
rollout_restart
Trigger a rolling restart of a deployment, daemonset, or statefulset by patching the pod template annotation with the current timestamp.
| Parameter | Type | Required | Description |
|---|---|---|---|
kind | string | yes | deployment, daemonset, or statefulset |
name | string | yes | Resource name |
namespace | string | yes | Namespace |
rollout_undo
Roll back a deployment to a previous revision.
| Parameter | Type | Required | Description |
|---|---|---|---|
kind | string | yes | deployment (currently the only supported kind) |
name | string | yes | Resource name |
namespace | string | yes | Namespace |
revision | number | no | Target revision number; omit or set to 0 for the previous revision |
apply_yaml
Apply a Kubernetes YAML manifest using server-side apply. Equivalent to kubectl apply --server-side.
| Parameter | Type | Required | Description |
|---|---|---|---|
yaml | string | yes | The full YAML manifest content |
cordon_node
Cordon or uncordon a node to prevent or allow new pod scheduling.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | Node name |
unschedulable | boolean | yes | true = cordon (prevent new pods), false = uncordon |
drain_node
Evict all pods from a node to prepare it for maintenance. Requires confirm=true to execute — call without it first to see which pods would be evicted.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | Node name |
force | boolean | no | Delete pods not managed by a controller (default false) |
ignore_daemonsets | boolean | no | Skip DaemonSet-managed pods (default true) |
delete_emptydir_data | boolean | no | Allow eviction of pods with emptyDir volumes (default false) |
confirm | boolean | no | Must be true to drain. Omit or set false to preview which pods would be evicted. |
Preview response (without confirm=true):
1{
2 "node": "node-1",
3 "would_evict": 12,
4 "would_skip": 4,
5 "pods_to_evict": ["production/api-pod-abc", "production/worker-pod-xyz"],
6 "message": "Set confirm=true to drain node node-1 (will evict 12 pods, skip 4)."
7}The pods_to_evict list is capped at 50 entries; a "truncated": true field is added when there are more.
trigger_cronjob
Manually trigger a CronJob by creating a Job from its template — equivalent to kubectl create job --from=cronjob/<name>.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | CronJob name |
namespace | string | yes | Namespace |
Returns the name of the created Job.
exec_command
Execute a one-shot command inside a running pod container and return combined stdout + stderr. Suitable for non-interactive commands (ls, env, cat /path, ps aux).
| Parameter | Type | Required | Description |
|---|---|---|---|
pod | string | yes | Pod name |
namespace | string | yes | Namespace |
container | string | no | Container name (defaults to first container) |
command | array | yes | Command and arguments, e.g. ["ls", "-la", "/tmp"] |
Non-zero container exit codes are returned as part of the result text (not as a tool error), so the AI can see the output even when the command fails.
switch_context
Switch the active Kubernetes context for all subsequent tool calls. All tools called after a successful switch_context will operate against the new cluster.
| Parameter | Type | Required | Description |
|---|---|---|---|
context | string | yes | Kubernetes context name (must exist in kubeconfig) |
Returns "Switched to context <name>" on success. Returns an error if the context is not found in the kubeconfig — the active context is not changed on error.
helm_rollback
Roll back a Helm release to a previous revision.
| Parameter | Type | Required | Description |
|---|---|---|---|
release | string | yes | Release name |
namespace | string | yes | Namespace |
revision | number | no | Target revision; omit or set to 0 for the previous revision |
Helm lifecycle tools (6)
helm_upgrade
Upgrade an existing Helm release, or install it if not present (--install).
| Parameter | Type | Required | Description |
|---|---|---|---|
release | string | yes | Release name |
namespace | string | yes | Namespace |
chart | string | yes | Chart reference: local path, repo/chart, or OCI reference |
values | string | no | Optional YAML string of values to merge over chart defaults |
Returns: { "release": "...", "status": "deployed", "revision": 3 }
helm_uninstall
Uninstall a Helm release and remove all associated Kubernetes resources. Requires confirm=true to execute — call without it first to see a preview.
| Parameter | Type | Required | Description |
|---|---|---|---|
release | string | yes | Release name |
namespace | string | yes | Namespace |
confirm | boolean | no | Must be true to uninstall. Omit or set false to preview what will be removed. |
helm_history
List all revisions of a Helm release (same as helm history).
| Parameter | Type | Required | Description |
|---|---|---|---|
release | string | yes | Release name |
namespace | string | yes | Namespace |
Authentication
podscape-mcp authenticates with the Kubernetes API using the credentials already present in your kubeconfig — exactly as kubectl does. This includes certificate-based auth, token-based auth, OIDC, exec plugins (e.g. aws eks get-token), and any other provider supported by client-go.
The MCP server does not connect to the Podscape desktop app or its sidecar. There is no separate token or shared secret to configure.
The permissions available to the MCP server are the same as those of the user or service account referenced by the active kubeconfig context. If your kubeconfig user only has read access to certain namespaces, the MCP tools will reflect that — they will return API errors for operations outside that scope.
Example workflows
Diagnose a failing pod in production
Ask your AI assistant:
"One of my pods in the production namespace is crash-looping. Can you find it and tell me what's wrong?"
The assistant will likely call:
list_failing_podswithnamespace=productionto find the podpod_summarywith the pod name and namespace to get status, events, and logs in one shot
Check cluster health before a deployment
Ask your AI assistant:
"Give me a quick health check of the cluster before I push the release."
The assistant will call:
cluster_healthto get node/pod counts and recent Warning events- Optionally
list_failing_podsfor a full list of unhealthy pods
Drain a node for maintenance
Ask your AI assistant:
"I need to take node-3 offline for maintenance. Drain it."
The assistant will:
- Call
drain_nodewithname=node-3(noconfirm) — receives the pod preview - Present the preview to you for confirmation
- Call
drain_nodeagain withconfirm=trueto execute
Debug a failing init container
Ask your AI assistant:
"The api-server pod keeps getting stuck in Init state. What's happening?"
The assistant will likely call:
describe_resourcewithresource=pods, name=api-server— gets the pod spec and events in one callget_pod_logswithinit_container=trueto see what the init container printed before failing
Switch clusters mid-session
Ask your AI assistant:
"Switch to the staging cluster and check if the same issue exists there."
The assistant calls:
list_contextsto see available contextsswitch_contextwith the staging context name- Any subsequent tool calls now operate against staging
Roll back a broken Helm release
Ask your AI assistant:
"The last deploy of the checkout-service Helm release broke something. Roll it back to the previous revision."
The assistant will likely call:
helm_statuswithrelease=checkout-serviceto confirm the current statehelm_historyto see available revisionshelm_rollbackwithrelease=checkout-serviceandrevision=0helm_statusagain to confirm the rollback succeeded
Troubleshooting
"error building kubeconfig from …"
The kubeconfig file does not exist at the expected path, or the path passed via --kubeconfig is wrong. Check that the file exists and is readable. If you use a non-standard path, set $KUBECONFIG or pass --kubeconfig explicitly.
"connection refused" or API server unreachable
The cluster referenced by the active context is not reachable. Verify with kubectl cluster-info. Common causes: VPN not connected, cluster is down, or the kubeconfig context points to a stale server address.
Tool calls return permission errors
The kubeconfig user does not have RBAC permission for the requested operation. Review the cluster role bindings for your user, or switch to a context with sufficient privileges.
"metrics unavailable (is metrics-server installed?)"
The get_metrics tool requires the Kubernetes Metrics Server to be running in the cluster. Install it with:
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yamlMCP server not appearing in the AI assistant
- Confirm the binary path in the MCP client config is correct and the binary is executable (
chmod +x). - On macOS, if Gatekeeper blocks the binary, run
xattr -dr com.apple.quarantine /usr/local/bin/podscape-mcp. - For Claude Desktop, restart the app after editing the config file.
- For Claude Code, start a new session after running
claude mcp add— MCP servers connect on session startup, not mid-session. - Run the binary manually to confirm it starts without errors:
/usr/local/bin/podscape-mcp --help
Tools operate on the wrong cluster after a context switch
Use the switch_context tool to change the active context mid-session — the server will reinitialise its client against the new cluster immediately. Alternatively, restart the MCP client session after running kubectl config use-context in your terminal.
API Reference
Every HTTP endpoint exposed by the Go sidecar on localhost:5050 — workloads, networking, RBAC, Helm, security, GitOps, WebSocket streams, and auth details.
The Go sidecar listens on 127.0.0.1:5050 by default. All endpoints except /health require the X-Podscape-Token header.
X-Podscape-Token: <token> # injected automatically by checkedSidecarFetch
RBAC denial header
Resource-list endpoints (/pods, /deployments, /crds, etc.) always return 200 OK. When the current user lacks list/watch permission for a resource, the response body is [] and the following header is set:
X-Podscape-Denied: true
The main-process getResources IPC handler detects this header and throws RBACDeniedError so the renderer store can differentiate "permission denied" from a genuinely empty namespace. The deniedSections Zustand store field tracks which sections are denied; ResourceList renders an "Access denied" banner for them.
HPA version
/hpas returns autoscaling/v2 objects (requires Kubernetes ≥ 1.23). The response includes spec.metrics and status.currentMetrics arrays used by HPADetail to render target-vs-current metric comparisons.
Health
| Method | Path | Description |
|---|---|---|
| GET | /health | Returns 200 OK when informers are synced (or in no-kubeconfig mode). Returns 503 while syncing. No auth required. |
Workloads
| Method | Path | Description |
|---|---|---|
| GET | /nodes | All cluster nodes |
| GET | /namespaces | All namespaces |
| GET | /pods | Pods (filter with ?namespace=) |
| GET | /deployments | Deployments |
| GET | /daemonsets | DaemonSets |
| GET | /statefulsets | StatefulSets |
| GET | /replicasets | ReplicaSets |
| GET | /jobs | Jobs |
| GET | /cronjobs | CronJobs |
| GET | /hpas | HorizontalPodAutoscalers |
| GET | /pdbs | PodDisruptionBudgets |
Networking
| Method | Path | Description |
|---|---|---|
| GET | /services | Services |
| GET | /ingresses | Ingresses |
| GET | /ingressclasses | IngressClasses |
| GET | /networkpolicies | NetworkPolicies |
| GET | /endpoints | Endpoints |
Config & Storage
| Method | Path | Description |
|---|---|---|
| GET | /configmaps | ConfigMaps |
| GET | /secrets | Secrets (values masked server-side) |
| GET | /pvcs | PersistentVolumeClaims |
| GET | /pvs | PersistentVolumes |
| GET | /storageclasses | StorageClasses |
RBAC
| Method | Path | Description |
|---|---|---|
| GET | /serviceaccounts | ServiceAccounts |
| GET | /roles | Roles |
| GET | /clusterroles | ClusterRoles |
| GET | /rolebindings | RoleBindings |
| GET | /clusterrolebindings | ClusterRoleBindings |
| GET | /crds | CustomResourceDefinitions |
| GET | /events | Events |
Kubernetes Operations
| Method | Path | Body / Params | Description |
|---|---|---|---|
| POST | /scale | {kind, name, namespace, replicas} | Scale a workload |
| POST | /delete | {kind, name, namespace} | Delete a resource |
| POST | /rollout/restart | {kind, name, namespace} | Rollout restart |
| GET | /rollout/history | ?kind=&name=&namespace= | Rollout revision history |
| POST | /rollout/undo | {kind, name, namespace, revision?} | Rollout undo |
| GET | /getYAML | ?kind=&name=&namespace= | Fetch resource manifest as YAML |
| POST | /apply | Raw YAML body | Apply a manifest (kubectl apply equivalent) |
| GET | /secret/value | ?name=&namespace=&key= | Reveal a single secret value |
| GET | /exec/oneshot | ?pod=&container=&namespace=&command= | Run a one-shot command in a container (non-interactive); returns {stdout, stderr, error?} |
| GET | /cp/from | ?pod=&container=&namespace=&path= | Copy a file from a container (streams as binary) |
| POST | /cp/to | ?pod=&container=&namespace=&path= | Copy a file into a container (binary body) |
Node Operations
| Method | Path | Body / Params | Description |
|---|---|---|---|
| POST | /node/cordon | ?name=&unschedulable= | Cordon (true) or uncordon (false) a node |
| POST | /node/drain | ?name= | Drain a node (cordon + pod eviction) |
CronJob Operations
| Method | Path | Body / Params | Description |
|---|---|---|---|
| POST | /cronjob/trigger | ?namespace=&name= | Create a Job from a CronJob manually |
Context Management
| Method | Path | Description |
|---|---|---|
| GET | /config/contexts | List all kubeconfig contexts |
| GET | /config/current-context | Active context name |
| POST | /config/switch | Switch active context {context} |
Metrics
| Method | Path | Description |
|---|---|---|
| GET | /metrics/pods | Pod CPU / memory (requires metrics-server) |
| GET | /metrics/nodes | Node CPU / memory (requires metrics-server) |
Prometheus
| Method | Path | Description |
|---|---|---|
| GET | /prometheus/status | Auto-discover Prometheus via k8s service proxy or manual URL |
| POST | /prometheus/query_range_batch | Batch PromQL range queries — 60s TTL cache + singleflight deduplication per query |
| POST | /prometheus/cache/clear | Evict all cached Prometheus results (called on context switch and manual refresh) |
Batch request body:
1{
2 "queries": [
3 { "query": "rate(container_cpu_usage_seconds_total[5m])", "label": "CPU" },
4 { "query": "container_memory_working_set_bytes", "label": "Memory" }
5 ],
6 "start": 1700000000,
7 "end": 1700003600
8}Batch response:
[
{ "label": "CPU", "points": [{ "t": 1700000000, "v": 0.02 }, ...] },
{ "label": "Memory", "points": [{ "t": 1700000000, "v": 134217728 }, ...], "error": "" }
]Caching behaviour: each (query, start, end, step) tuple is cached for 60 seconds on success (5 seconds on error). Concurrent identical requests are deduplicated via singleflight — only one HTTP call is made to Prometheus regardless of how many charts mount simultaneously. POST /prometheus/cache/clear increments an atomic generation counter, making all pre-clear in-flight writes land under orphaned keys that new readers never look up; no goroutine cancellation is needed.
Helm
| Method | Path | Description |
|---|---|---|
| GET | /helm/list | Installed Helm releases |
| GET | /helm/status | Release status ?name=&namespace= |
| GET | /helm/values | Release values ?name=&namespace= |
| GET | /helm/history | Release history ?name=&namespace= |
| POST | /helm/rollback | Roll back a release |
| POST | /helm/upgrade | ?name=&namespace=&chart=&version= |
| POST | /helm/uninstall | Uninstall a release |
| GET | /helm/repos | List configured Helm repositories |
| GET | /helm/repos/search | Search charts ?q=&repo=&limit=&offset= |
| GET | /helm/repos/versions | Chart versions ?chart=&repo= |
| GET | /helm/repos/values | Default values for a chart version |
| POST | /helm/repos/refresh | Re-fetch repo indexes (SSE stream) |
| POST | /helm/install | Install a chart (SSE stream) |
Install body:
1{
2 "chart": "nginx",
3 "repo": "bitnami",
4 "version": "15.0.0",
5 "name": "my-nginx",
6 "namespace": "default",
7 "values": "replicaCount: 2\n"
8}Provider Detection
| Method | Path | Description |
|---|---|---|
| GET | /providers | Detect installed service mesh and ingress providers (Istio, Traefik v2/v3, NGINX Inc, NGINX Community) |
Response:
1{
2 "istio": true,
3 "traefikV3": false,
4 "traefikV2": false,
5 "nginxInc": false,
6 "nginxCommunity": true
7}Detection methods:
- Istio —
networking.istio.ioAPI group present - Traefik v3 —
traefik.ioAPI group present - Traefik v2 —
traefik.containo.usAPI group present - NGINX Inc —
k8s.nginx.orgAPI group present - NGINX Community — IngressClass controller field contains
ingress-nginx
Custom Resources
| Method | Path | Description |
|---|---|---|
| GET | /customresource | List any CRD using the dynamic client |
Query params: ?crd=<plural>.<group>&namespace=<ns>
Example: ?crd=ingressroutes.traefik.io&namespace=default
Returns a raw JSON array of the matched custom resources. Returns an error (not a silent empty array) when the CRD does not exist or the request fails.
Owner Chain
| Method | Path | Description |
|---|---|---|
| GET | /owner-chain | Traverses owner references up (ancestors) and down (descendants) |
Query params: ?kind=Pod&name=my-pod&namespace=default
Response:
1{
2 "ancestors": [
3 { "kind": "ReplicaSet", "name": "my-deploy-abc", "namespace": "default", "uid": "...", "found": true },
4 { "kind": "Deployment", "name": "my-deploy", "namespace": "default", "uid": "...", "found": true }
5 ],
6 "descendants": {
7 "Pod": []
8 }
9}Security
| Method | Path | Description |
|---|---|---|
| POST | /security/scan | Full audit: engine + Trivy + Kubesec (SSE stream) |
| POST | /security/kubesec | Single resource Kubesec audit |
| POST | /security/kubesec/batch | Batch Kubesec audit (worker pool, 8 concurrent) |
| POST | /security/trivy/images | Trivy image scan for selected images (SSE stream) |
SSE events (for streaming endpoints):
progress— real-time log linesresult— final JSON payloaderror— error message
Topology
| Method | Path | Description |
|---|---|---|
| GET | /topology | Cluster topology graph (nodes → pods → services) |
TLS Certificates
| Method | Path | Description |
|---|---|---|
| GET | /tls-certs | Cluster-wide certificate inventory with expiry tracking |
GitOps
| Method | Path | Description |
|---|---|---|
| GET | /gitops | Argo CD / Flux resource overview |
| POST | /gitops/reconcile | {kind, name, namespace} |
| POST | /gitops/suspend | {kind, name, namespace, suspend} |
Debug Pod
| Method | Path | Description |
|---|---|---|
| POST | /debugpod/create | Launch an ephemeral debug pod on a specified node |
Port Forward
| Method | Path | Description |
|---|---|---|
| POST | /stopPortForward | ?id= — stop an active port-forward tunnel |
| WS | /portforward | Port-forward lifecycle events (ready / error / exit) |
Real-time (WebSocket)
| Path | Description |
|---|---|
ws://127.0.0.1:5050/logs | Real-time container log stream |
ws://127.0.0.1:5050/exec | Interactive PTY exec into a container |
ws://127.0.0.1:5050/portforward | Port-forward lifecycle events (ready / error / exit) |
Security Hub
How Kubesec config audits and Trivy CVE scans work, the split-panel UI, background scan flow, pod deduplication, and CSV/JSON export.
The Security Hub provides a unified interface for auditing cluster security, combining a built-in scanner engine with optional Trivy and Kubesec integrations.
Scanning Engines
1. Built-in Scanner Engine (src/renderer/utils/scanner/)
A rule-based engine that runs entirely in the renderer against the already-loaded resource cache — no network call required.
- Rules are composable functions:
validate(resource) → Issue[] - Results are available immediately when opening the Security Hub (no scan trigger needed).
Built-in rules (src/renderer/utils/scanner/bestPracticeRules.ts):
| Rule | Check |
|---|---|
| Missing Resource Limits | Containers without CPU or Memory limits |
| Latest Image Tag | Containers using the :latest tag |
| Missing Liveness Probe | Containers without a liveness probe |
| Missing Readiness Probe | Containers without a readiness probe |
| Sensitive Env Variable | Plain-text environment variables with names matching PASSWORD, SECRET, TOKEN, KEY, etc. |
2. Static Configuration Analysis — Kubesec
- Engine: Kubesec.io — integrated as a Go package in the sidecar.
- Endpoint:
POST /security/kubesec/batch - Concurrency: Worker pool with 8 concurrent goroutines for high-throughput batch scoring.
- Scoring: Kubesec raw scores are normalized to
critical(< 0),warning(0–3), andinfo(> 3) levels.
3. Dynamic Image Vulnerability Scanning — Trivy
- Engine: Aqua Security Trivy — invoked via
os/execfrom the sidecar. - Endpoint:
POST /security/trivy/images(SSE stream) - Deduplication: Images are deduplicated cluster-wide before scanning — each unique tag is scanned only once regardless of how many pods use it.
- SSE Streaming: Scan progress (
progressevents) and the final report (resultevent) are streamed in real-time. The sidecar compacts Trivy's pretty-printed JSON withjson.Compactbefore transmission so the JSON is sent as a single-line SSE payload and does not interfere with SSE message boundaries.
Custom Scan Options
The Security Hub supports scoped scans to reduce noise:
- Namespace filter: limit scanning to one or more namespaces.
- Kind filter: scan only specific resource types (e.g. Pods, Deployments).
- Engine toggles: run any combination of the built-in engine, Kubesec, and Trivy independently.
Pod deduplication: Pods are excluded from scans by default to avoid duplicate resource findings, because a pod's security posture is usually represented by its parent controller (Deployment, StatefulSet, DaemonSet, etc.). This does not reduce Trivy image coverage: images referenced by included controllers are still discovered and scanned once cluster-wide via image deduplication. To include pods explicitly, select "Pod" in the kind filter of a custom scan.
Background Scans
Full and custom scans can run in the background while you use other panels:
- Click the ▾ arrow next to the Full Scan button and choose Run in Background.
- A floating pill appears in the bottom-right corner of every screen while the scan is running. Click it to jump back to Security Hub.
- When the scan finishes, a system notification is delivered with a summary (number of affected resources, or "No issues found").
Background scans require notification permission; the app requests it automatically on first background scan.
UI Features
| Feature | Description |
|---|---|
| Flat / grouped view | Toggle between a flat resource list and grouping by namespace |
| System filter | Auto-hides kube-system, kube-node-lease, cert-manager, and Node resources; toggle "Show System" to reveal |
| Colored kind badges | Every row shows a colored pill (Deployment, StatefulSet, DaemonSet, etc.) for instant resource-type identification |
| Config / CVE panels | Expanded rows display a red "Configuration Issues" card and an orange "Image Vulnerabilities" card separately |
| CVE detail | Each vulnerability shows the image name, package name, fix version, CVE ID, and severity |
| Severity filter tabs | Filter results to Critical-only or Warning-only |
| Sortable columns | Sort by resource name, namespace, kind, config issues, CVE count, or combined score |
| Navigate to resource | Click the ↗ button on any row to open that resource's detail panel directly |
| Export | Download filtered results as CSV or JSON for external reporting |
Score Model
Each resource in the table receives a combined risk score:
| Score | Indicator | Condition |
|---|---|---|
| 2 — Critical | Red dot | Has CRITICAL or HIGH CVEs from Trivy |
| 1 — Warning | Amber dot | Has config issues from the engine or Kubesec |
| 0 — OK | Grey dot | No issues found |
Navigate to Resource
Every row in the Security Hub has a ↗ icon button (visible on hover) that calls navigateToResource(kind, name, namespace). This:
- Switches the active section in the left sidebar to the resource's kind (e.g. Pods, Deployments).
- Loads the resource list for that section.
- Selects and opens the matched resource's detail panel.
This is the same navigation action used by the Ownership Chain tree visualization.
Application & System Hardening
To ensure the security and stability of the application and the cluster it manages, Podscape implements several system-level security controls:
1. Ephemeral Port Forwarding (TOCTOU Prevention)
Programmatic port forwarding previously searched for a free local port using freeLocalPort() and then bound it. This left a Time-of-Check to Time-of-Use (TOCTOU) window where another process could grab the port.
To eliminate this vulnerability:
- The Go sidecar binds port
0(e.g.,127.0.0.1:0), instructing the operating system to allocate a free ephemeral port atomically. - Once the tunnel is successfully established, the sidecar retrieves the allocated port via
pf.GetPorts()and returns it to the client.
2. Helm Downloader Resource Limits & Timeouts
To protect the sidecar from memory exhaustion (Denial of Service) and hanging network calls when downloading Helm repository assets (such as massive index.yaml files or chart values):
- Body Limit: A strict limit of 64MB is enforced on all HTTP response bodies read when downloading Helm repository indexes or configuration files.
- Network Timeouts: A strict timeout of 60 seconds is applied to all outgoing HTTP connection and read phases during Helm downloads.
3. Namespace Fallback Check in RBAC Probes
In multi-tenant clusters or restricted environments where a user does not have cluster-wide resource access (such as cluster-scoped SelfSubjectAccessReview permissions), checking permissions at the root (namespace "") returns denied for namespace-scoped resources.
To address this, Podscape's RBAC probe performs a fallback check:
- If a namespace-scoped resource query at the cluster level (namespace
"") is denied, the probe retries the SAR check specifically inside the"default"namespace. - An access verb is marked allowed if either the cluster-wide or the
"default"namespace check succeeds (OR-logic). - Cluster-scoped resources (e.g.,
Nodes,Namespaces,PersistentVolumes) are skipped during the"default"namespace check to prevent redundant, incorrect probes.
Keyboard Shortcuts
All keyboard shortcuts and the full command palette section index — every alias that ⌘K / Ctrl+K recognises.
This page is the exhaustive reference for every keyboard shortcut in Podscape. Shortcuts are discovered directly from source code and reflect the current implementation.
Platform notation used in this document:
⌘— Command key (macOS only)Ctrl— Control key (Windows / Linux)- Where a shortcut says
⌘/Ctrl, use⌘on macOS andCtrlon Windows/Linux.
Global Shortcuts
These shortcuts are active anywhere in the application, regardless of which section is open.
| Shortcut | Platform | Action |
|---|---|---|
⌘ K | macOS | Open / close the Command Palette |
Ctrl K | Windows / Linux | Open / close the Command Palette |
Command Palette
Opened with ⌘K / Ctrl+K, the Command Palette lets you jump to any section or navigate directly to a specific resource by name.
Navigation keys (while the palette is open)
| Key | Action |
|---|---|
| Type to search | Filter sections and resources by name or keyword |
↓ Arrow Down | Move selection down through results |
↑ Arrow Up | Move selection up through results |
Enter | Jump to the selected section or open the selected resource |
Escape | Close the palette without navigating |
How search works
The palette searches two pools simultaneously:
- Sections — matched against the section label, its internal ID, and a set of topic keywords (see table below). Up to 5 section results are shown.
- Resources — matched against the
metadata.nameof every resource that is already loaded in the current context. Up to 12 resource results are shown.
Selecting a section result navigates to that section. Selecting a resource result switches to the correct namespace and section and opens the resource's detail panel.
Section Quick-Jump Reference
The table below lists every section searchable through the Command Palette, along with all keywords that will surface it in results.
| Section Label | Internal ID | Search Keywords |
|---|---|---|
| Dashboard | dashboard | home, overview |
| Pods | pods | workload |
| Deployments | deployments | workload |
| DaemonSets | daemonsets | workload |
| StatefulSets | statefulsets | workload |
| ReplicaSets | replicasets | workload |
| Jobs | jobs | workload, batch |
| CronJobs | cronjobs | workload, batch, schedule |
| HPAs | hpas | autoscaling, scale |
| PodDisruptionBudgets | pdbs | pdb, disruption |
| Services | services | network, svc |
| Ingresses | ingresses | network, routing |
| Ingress Classes | ingressclasses | network |
| Network Policies | networkpolicies | network, policy |
| Endpoints | endpoints | network |
| ConfigMaps | configmaps | config, cm |
| Secrets | secrets | config, credentials |
| PVCs | pvcs | storage, volume, persistent |
| PVs | pvs | storage, volume, persistent |
| Storage Classes | storageclasses | storage |
| Service Accounts | serviceaccounts | rbac, auth |
| Roles | roles | rbac, auth, permission |
| Cluster Roles | clusterroles | rbac, auth |
| Role Bindings | rolebindings | rbac, auth |
| Cluster Role Bindings | clusterrolebindings | rbac, auth |
| Nodes | nodes | cluster, infrastructure |
| Namespaces | namespaces | cluster |
| CRDs | crds | cluster, custom, resources |
| Events | events | observe, logs, warning |
| Metrics | metrics | observe, cpu, memory, usage |
| Unified Logs | unifiedlogs | observe, logs, stream |
| Port Forwards | portforwards | network, tunnel, forward |
| Network Map | network | topology, visualize |
| Connectivity | connectivity | test, ping, curl |
| Debug Pods | debugpod | debug, shell, exec |
| Security Hub | security | scan, trivy, kubesec, vulnerability |
| TLS Certificates | tls | cert, ssl, x509, expiry |
| GitOps | gitops | flux, argo, argocd, kustomize, gitops |
| Helm Charts | helm | helm, releases, charts, package |
| Settings | settings | config, preferences, theme |
Resource List
The resource list table is the main panel for all Kubernetes resource types (pods, deployments, services, etc.). The following shortcuts are active when focus is not inside a text input or textarea.
| Key | Action |
|---|---|
Escape | Close an open context menu; or close an open YAML viewer / loading spinner; or close an open delete confirmation dialog; or close an open port-forward dialog; or close an open scale dialog |
Delete | Open the bulk-delete confirmation for the currently selected rows (if one or more rows are selected), or open the single-resource delete confirmation for the highlighted resource |
Backspace | Same as Delete — opens bulk-delete or single-resource delete confirmation |
Note: Delete and Backspace only trigger when focus is outside any <input> or <textarea> element.
Pod Detail Panel
The following shortcuts are active when a pod is selected and its detail panel is open. They do not fire when focus is inside a text input or textarea.
| Shortcut | Platform | Action |
|---|---|---|
⌘ T | macOS | Open an interactive shell (exec) into the selected container |
Ctrl T | Windows / Linux | Open an interactive shell (exec) into the selected container |
⌘ L | macOS | Switch to the Logs tab and enter fullscreen log view |
Ctrl L | Windows / Linux | Switch to the Logs tab and enter fullscreen log view |
⌘ D | macOS | Close fullscreen log view (only when log fullscreen is active) |
Ctrl D | Windows / Linux | Close fullscreen log view (only when log fullscreen is active) |
Escape | All | Close fullscreen log view (when fullscreen is active) |
Exec / Terminal Panel
The exec panel is the full-screen terminal that opens when you shell into a container.
| Shortcut | Platform | Action |
|---|---|---|
⌘ D | macOS | Close the exec panel (only fires when focus is not in an input or textarea) |
Ctrl D | Windows / Linux | Close the exec panel (only fires when focus is not in an input or textarea) |
Escape | All | Close the exec panel (only when the file-transfer sub-panel is not open) |
Tab | All | Sent to the PTY as a tab-completion character (browser focus-navigation is suppressed) |
Enter (in path input) | All | Submit a file upload or download when the remote path field is focused |
Note: ⌘D / Ctrl+D is shown in the exec panel header as a reminder hint.
Connectivity Tester
The Connectivity Tester panel (connectivity section) supports one keyboard shortcut.
| Shortcut | Platform | Action |
|---|---|---|
⌘ Enter | macOS | Run the connectivity test (when the form is valid and ready to run) |
Ctrl Enter | Windows / Linux | Run the connectivity test (when the form is valid and ready to run) |
Delete Confirmation Dialog
When a resource delete confirmation dialog is open and you have typed the resource name into the confirmation field:
| Key | Action |
|---|---|
Enter | Confirm and execute the deletion (only when the typed name matches the resource name) |
Notes
- All
⌘/Ctrlshortcuts usee.metaKeyon macOS ande.ctrlKeyon Windows/Linux — this is detected automatically viasrc/renderer/utils/platform.ts. - Shortcuts that require focus to be outside a text field check
document.activeElement.tagName !== 'INPUT'and!== 'TEXTAREA'before firing. - The terminal inside ExecPanel uses xterm.js. Standard terminal key sequences (Ctrl+C, Ctrl+Z, arrow history, etc.) are handled natively by the PTY and are not listed here as they are shell-level, not app-level, shortcuts.
Troubleshooting
Fixes for sidecar startup failures, RBAC-denied sections, build errors, and step-by-step recovery procedures.
This guide covers common issues, their root causes, and step-by-step fixes. Issues are grouped by area.
Sidecar Issues
The Go sidecar (podscape-core) is the backend process that handles all Kubernetes API calls. Most connectivity and startup problems trace back to it.
"Sidecar Connection Failed" dialog on launch
Symptom: A dialog box appears at startup reading "The Podscape backend (Go sidecar) failed to start" and the app quits.
Cause: One of three things happened before the sidecar became healthy:
- The binary is missing at the expected path.
- The sidecar process exited immediately (bad kubeconfig, missing Go binary, permissions issue).
- The sidecar failed to respond on its port within 90 seconds (180 polls × 500 ms).
Fix:
-
Check the binary exists. In development:
bashls go-core/podscape-coreIf it is missing, build it:
bashcd go-core && go build ./cmd/podscape-core/In production, the binary is bundled at
resources/bin/podscape-coreinside the app package. -
Check executable permissions (macOS/Linux). The app applies
chmod 755automatically, but if you copied the binary manually it may lack execute permission:bashchmod +x go-core/podscape-core -
Check port 5050. See Port 5050 Already In Use below.
-
Check your kubeconfig. The sidecar reads kubeconfig at startup. If the file references a cluster that no longer exists, the process may exit before becoming healthy. Verify with:
bashkubectl config view
{: .note } The error dialog includes the last 30 lines of sidecar stderr. Read them carefully — they will usually name the specific failure.
Sidecar crash banner during use ("Reconnect" button)
Symptom: A red banner appears at the top of the window: "Connection to cluster lost — the backend process exited unexpectedly." A Reconnect button is shown.
Cause: The podscape-core process exited after startup completed. This can happen due to an unhandled panic in the Go process, an OOM kill, or a forceful termination by the OS.
Fix:
- Click Reconnect. This calls
sidecar:restartover IPC, which relaunches the binary and reloads the renderer once the sidecar is healthy again. - If the sidecar keeps crashing, open the system console (macOS: Console.app, Linux:
journalctl) and look for crash reports frompodscape-core. - In development, sidecar logs are printed directly to the terminal running
npm run dev. Check there for a Go stack trace.
{: .note } The crash banner only appears when the sidecar exits after startup completed. If it exits during the startup health-check window, the "Sidecar Connection Failed" dialog appears instead.
Sidecar unresponsive / requests timing out
Symptom: The app loads but resource lists spin indefinitely, or operations (scale, delete, etc.) hang without returning.
Cause: The sidecar process is running but not responding to HTTP requests. This can happen if the cluster API server is very slow, the sidecar is blocked on a large informer cache sync, or there is a network issue between the machine and the cluster.
How the retry logic works: Every IPC call to the sidecar goes through sidecarFetch(), which retries up to 20 times with 500 ms delays on ECONNREFUSED, UND_ERR_SOCKET, and socket hang-up errors. That means up to 10 seconds of retrying before an error surfaces.
Fix:
- Open the Metrics section to confirm the cluster API server is reachable at all.
- Check your VPN connection if the cluster is remote.
- Try switching to a different context and back — this triggers a full context switch which re-initialises the sidecar's clientset and informers.
- If the sidecar is stuck on informer sync for a very large cluster, wait up to 90 seconds after launch for it to finish the initial cache warm-up.
- Restart Podscape entirely to get a fresh sidecar process.
Port 5050 already in use
Symptom: Sidecar fails to start with an error message mentioning port 5050 or bind: address already in use.
Cause: Another process is occupying TCP port 5050 on 127.0.0.1.
How Podscape handles this: The sidecar startup code probes port 5050 with a test TCP bind. If it is occupied, it falls back to a random ephemeral port chosen by the OS and logs: Port 5050 in use — using port <N>. The renderer automatically uses the port that was actually bound.
Fix: If you see the error despite the fallback logic, the sidecar process itself failed to bind. Find and stop the conflicting process:
1# macOS / Linux
2lsof -i :5050
3kill <PID>
4
5# Windows
6netstat -ano | findstr :5050
7taskkill /PID <PID> /FThen relaunch Podscape.
Kubeconfig and Context Issues
No kubeconfig found on first launch
Symptom: The app shows the onboarding screen ("KubeConfig Onboarding") instead of the normal sidebar and resource panels.
Cause: Podscape could not find a kubeconfig file at any of the default search paths (~/.kube/config, KUBECONFIG environment variable, or any path previously saved in settings).
Fix:
- Ensure
~/.kube/configexists and is readable:bashcat ~/.kube/config - If your kubeconfig is at a non-standard path, set the
KUBECONFIGenvironment variable before launching:bashKUBECONFIG=/path/to/my/kubeconfig open /Applications/Podscape.app - Use the onboarding screen's file picker to browse to your kubeconfig.
- In Settings, the kubeconfig path can be set explicitly and persisted to
~/.podscape/settings.json.
Context switch fails or hangs
Symptom: Clicking a context in the sidebar shows "Connecting…" or "Loading namespaces…" indefinitely, or the UI resets to the previous context with an error toast.
Cause: Context switches have a 15-second timeout applied to both the switchContext and getNamespaces calls. If either exceeds 15 seconds, the switch is rolled back: the sidecar and the renderer both revert to the previous context.
Common causes: cluster API server unreachable, expired credentials, VPN not connected, or an EKS/GKE token that requires re-authentication.
Fix:
- Check that the cluster API endpoint is reachable from your machine:
bash
kubectl --context=<context-name> cluster-info - Refresh credentials if using short-lived tokens (EKS, GKE, OIDC):
bash
# EKS aws eks update-kubeconfig --name <cluster> --region <region> # GKE gcloud container clusters get-credentials <cluster> --zone <zone> - Check VPN status for private clusters.
- If the timeout is consistently too short for a slow cluster, see Sidecar Unresponsive for general connectivity advice.
The error toast in the UI will include either timed out after 15s or the raw error message from the Kubernetes client, which helps pinpoint the problem.
Cluster unreachable after switching
Symptom: Context switch completes but all resource lists show errors or empty state. The dashboard shows no nodes.
Cause: The getNamespaces connectivity check passed (so the switch completed), but subsequent resource fetches are failing. This often means the cluster's API server is intermittently unavailable or the authenticated user lacks read access to most resources.
Fix:
- Verify with kubectl directly:
bash
kubectl --context=<context-name> get nodes - Check the RBAC section below if lists show the amber "Access denied" banner instead of errors.
- Use the Sync button to retry the current section manually.
RBAC / Access Denied
Sections show an amber "Access denied" banner
Symptom: Navigating to a resource section (e.g. Secrets, ClusterRoles) shows an amber badge reading "Access denied — your RBAC role does not allow listing this resource."
Cause: The sidecar detected that your Kubernetes user does not have list and watch permissions for that resource type. The sidecar returns a 200 response with an empty array and the header X-Podscape-Denied: true. The main process throws a typed RBACDeniedError, and the renderer adds the section to deniedSections. The amber banner is rendered instead of the empty-list state.
This is by design — denied sections are surfaced clearly rather than silently showing empty tables.
How the RBAC probe works
On every successful context switch, the Go sidecar runs a concurrent SelfSubjectAccessReview (SAR) probe against all 28 resource types it manages. The probe checks both the list and watch verbs for each resource. All 56 SAR requests are issued concurrently (bounded to 8 goroutines) and typically complete in under one second.
Three outcomes are possible:
| Outcome | Behaviour |
|---|---|
| SAR API unavailable (error) | All informers start unconditionally (pre-RBAC permissive mode) |
| Resource explicitly denied | Informer skipped; handler returns 200 [] + X-Podscape-Denied: true |
| Resource allowed | Informer starts normally; data is served |
deniedSections is cleared on every context switch, so permissions are always re-evaluated when you change clusters.
You have permissions but still see "Access denied"
Symptom: You know your user has access (you can kubectl get secrets fine), but the Secrets section in Podscape shows the denied banner.
Cause: The SAR probe checks the list and watch verbs. If your RBAC role only grants get or uses a very narrow resource name restriction (e.g. only a specific secret name), the SAR will return Allowed: false for list.
Fix:
- Verify the exact verbs your role grants:
bash
kubectl auth can-i list secrets --as=<your-serviceaccount-or-user> kubectl auth can-i watch secrets --as=<your-serviceaccount-or-user> - Both must return
yesfor Podscape to serve the section. - If the SAR probe itself failed (network error during the probe), the sidecar falls back to permissive mode and all sections should load. If this is happening, check the sidecar logs for
[RBAC] probemessages. - Switch context and switch back to re-run the RBAC probe after any role changes take effect.
{: .note }
Aggregated ClusterRoles can make kubectl auth can-i return yes while a direct SelfSubjectAccessReview returns Allowed: false in some edge cases. If this affects you, re-bind roles directly rather than through aggregation.
Build and Development Issues
See Development Guide for full build setup instructions.
window.kubectl.* methods appear as undefined
Symptom: At runtime the renderer throws errors like window.kubectl.getPods is not a function or Cannot read properties of undefined (reading 'getPods').
Cause: The preload script (src/preload/index.js) is stale. Vite's hot-module replacement updates renderer files but does not always trigger a full preload rebuild. The renderer is then running against an old version of the preload bundle that does not expose the expected API.
Fix:
Stop and fully restart the dev server:
# Stop with Ctrl+C, then:
npm run devA hard restart forces electron-vite to rebuild all three processes (main, preload, renderer) from scratch.
node-pty spawn-helper lacks execute permission
Symptom: Opening a terminal tab or exec-into-container session fails immediately. You may see errors like spawn EACCES or the terminal window opens but immediately closes.
Cause: On macOS, the prebuilt spawn-helper binary inside node-pty ships without execute permission (-rw-r--r-- instead of -rwxr-xr-x). This binary is required for PTY session creation.
Fix (automatic): The postinstall script in package.json applies chmod +x automatically when you run npm install. If it worked, you should not see this issue.
Fix (manual): Run the fix yourself:
chmod +x node_modules/node-pty/prebuilds/darwin-*/spawn-helperIf you are on an M-series Mac and see darwin-arm64:
chmod +x node_modules/node-pty/prebuilds/darwin-arm64/spawn-helperAfter applying the fix, restart npm run dev — the running Electron process caches the binary load.
Go binary not found in dev mode
Symptom: On first launch in development, the startup dialog reports Sidecar binary not found at: <path>/go-core/podscape-core.
Cause: The Go sidecar binary must be compiled separately before starting the dev server. It is not built by npm run dev.
Fix:
cd go-core && go build ./cmd/podscape-core/
cd ..
npm run devAfter the initial build, you only need to rebuild the binary when you change Go source files under go-core/.
{: .note }
In production builds, npm run build compiles the Go binary as part of the full build sequence. The binary is then bundled into the app at resources/bin/podscape-core via extraResources in package.json.
Auto-Updater Issues
The auto-updater only runs in production builds (not in npm run dev). It checks for updates 5 seconds after launch.
Update download fails
Symptom: The update banner appears but clicking Download produces an error, or the download progress stalls.
Cause: The updater fetches the release artifact from GitHub Releases. Download failures are typically network-related: a firewall, proxy, or a transient GitHub outage.
Fix:
- Check your internet connection and any proxy settings.
- Wait a few minutes and use Check for Updates in Settings to retry.
- As a fallback, download the installer directly from the GitHub Releases page and install manually.
Update banner persists after install
Symptom: You clicked Install & Restart, but the update banner reappears after the app restarts, showing the same version.
Cause: electron-updater is configured with autoInstallOnAppQuit = true. Calling quitAndInstall(false, true) triggers a quit-and-relaunch sequence. If the installation step fails silently (e.g., due to a permissions issue with the app bundle), the app relaunches at the old version.
Fix:
- Download the latest installer from GitHub Releases and run it directly. This bypasses the in-app updater entirely.
- On macOS, if the app is in a read-only location (e.g., mounted DMG), move it to
/Applicationsbefore installing the update.
How to check the current version
Open Settings (gear icon in the sidebar) and look at the version number displayed at the bottom of the settings panel. You can also check About Podscape from the macOS app menu.
Performance Issues
Large clusters with many resources
Symptom: Switching sections is slow, the UI freezes briefly after a context switch, or the sidecar takes a long time to start on large clusters.
Cause: The Go sidecar uses Kubernetes shared informers to cache resources in memory. On clusters with thousands of pods, nodes, or events, the initial informer sync can take 10–30 seconds. The health check polls every 500 ms for up to 90 seconds, so Podscape will wait for this sync to complete before showing the main window.
Mitigations:
- Use the namespace filter — switching from "All Namespaces" to a specific namespace dramatically reduces the number of resources loaded into the renderer.
- Avoid navigating to high-cardinality sections (Events, Pods across all namespaces) on very large clusters. Use the search filter to narrow results before selecting a resource.
- The informer cache is shared across all sections, so the cost is paid once at startup, not on every section switch.
Log streaming slowdowns
Symptom: Viewing logs in the Pod detail panel becomes slow or the terminal lags when streaming high-volume logs.
Cause: High log throughput from a very chatty container floods the WebSocket connection and xterm.js rendering buffer.
Fix:
- Use the container filter in the pod detail panel to stream only the relevant container rather than all containers simultaneously.
- Open a terminal session (Multi-Terminal section) and use
kubectl logs --since=1m -f <pod>withgrepto filter server-side before the output reaches the UI. - Consider reducing the log verbosity of the container if it is under your control.
Security scan taking too long
Symptom: The Security Hub scan runs for a long time or appears to hang.
Cause: The security scan pulls image vulnerability data from Trivy, which fetches and caches vulnerability databases on first run. The first scan per image can take 30–60 seconds on a slow connection. Scanning clusters with many unique images multiplies this cost.
Fix:
- Ensure Trivy is installed and its database is up to date:
bash
trivy image --download-db-only - Run the scan in a namespace with fewer workloads first to verify Trivy is working correctly before scanning the whole cluster.
- If Trivy is not installed, Security Hub's static policy checks (privilege escalation, host network, missing resource limits) still run immediately without it — only the CVE scan requires Trivy.