CodingProtocols
  • Services
  • About
Get Started

Coding Protocols Insider

Get our DevOps playbooks, infrastructure patterns, and cloud engineering deep dives straight to your inbox.

No spam. No fluff. Just engineering. Unsubscribe anytime.

Our Mission

Deep dives, production-ready playbooks, and tools for platform and cloud engineers. No fluff.

Company

  • Services
  • About
  • Blog

Products

  • Podscape
  • Podscape Docs
  • Pint
  • Novique
  • All Apps

Topics

  • News & Digests
  • AI & Data
  • Cloud Engineering
  • DevOps & Platform
  • Kubernetes
  • Leadership & Strategy
  • Security

Series

  • Troubleshooting
  • Comparisons
  • Explainers
  • AWS Guides
  • AI Infrastructure
  • CI/CD
  • Cloud & AI Digest
  • Kubernetes Hub

Resources

  • Tutorials
  • Free Tools
  • Article Series
  • Glossary
  • FAQ
  • Hot Tips
  • Platform Roadmap

Contact

contact@codingprotocols.com
Raebareli, UP, India - 229404
Send a message →

© 2026 Coding Protocols Private Limited. All rights reserved. Registered in India.

Terms•Privacy•Refunds
    Back to Podscape
    OverviewArchitectureFeatures GuideMCP ServerAPI ReferenceSecurity HubKeyboard ShortcutsTroubleshootingFull site
    Podscape Docs
    1 of 8

    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

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

    Feature Overview

    FeatureDescription
    Resource Browser28 built-in Kubernetes resource types with live informer-backed cache
    RBAC-aware startupConcurrent SelfSubjectAccessReview probe at startup; denied sections show an "Access denied" banner instead of errors
    Modular ArchitectureRefactored renderer shell (Layout/Router/Overlay) and granular type system for better maintainability
    Go SidecarStandalone podscape-core binary — HTTP server split across 16 handler files, shared informer cache, RBAC probe, and centralized resource metadata (k8sutil)
    Service Mesh SupportIstio, Traefik v2/v3, NGINX Inc, NGINX Community — auto-detected per cluster via API group discovery
    HPA v2 MetricsFull autoscaling/v2 metric display: resource, container-resource, Pods, External targets vs current
    CronJobsManual trigger support (instantiate Job from CronJob) and recent job history
    Prometheus ChartsCPU, memory, and network time-series charts in Pod / Node / Deployment detail panels
    Helm ManagementList releases, inspect values, view history, rollback, and browse/install from Helm repositories; connection retry logic
    Security HubKubesec config audit + Trivy image CVE scanner; config/CVE split panels, kind badges, background scan with system notification, pod deduplication; export as CSV / JSON
    Port ForwardingOne-click tunnel setup with auto port detection and live status
    Container ShellPTY exec-into-container via xterm.js
    Log StreamingReal-time WebSocket log streaming with search and fullscreen mode
    Network TopologyForce-directed graph of pod-to-service relationships with cross-namespace connectivity testing
    TLS DashboardCluster-wide certificate inventory with expiry tracking
    GitOps PanelArgo CD / Flux resource overview
    Debug PodLaunch an ephemeral debug container on any node
    Node OpsCordon, uncordon, and drain nodes with safety checks
    Owner ChainInteractive tree visualization showing ancestor and descendant resources
    MCP Serverpodscape-mcp — expose your cluster as tools for AI assistants (Claude, Cursor, etc.)
    Kubeconfig OnboardingGuided setup when no kubeconfig is detected on first launch
    Command PaletteCmd+K / Ctrl+K fuzzy search across all 50+ sections and resources
    Production Context ProtectionRed border + banner when connected to a context marked as production in Settings
    Unified Log StreamingAggregate real-time logs from multiple pods simultaneously with per-pod color coding and search
    Connectivity TesterPod-to-pod / pod-to-service network diagnostics with curl, netcat, and ping; automated DNS→TCP→HTTP flow
    Auto-UpdaterIn-app update checks with download progress and one-click install
    Kubectl Plugin PanelCurated kubectl plugins (via Krew) with dedicated UIs — install, run, and view output without leaving the app
    Panel TogglesEnable or disable Plugins, GitOps, and Network panels from Settings — sidebar updates immediately
    Next Architecture
    Podscape Docs
    2 of 8

    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.
    SliceResponsibility
    clusterSliceContext/namespace selection, RBAC denied tracking, provider detection trigger; on context switch clears inFlightSections and evicts the Go Prometheus cache
    navigationSliceActive section, theme, sidebar width, search state, tour state (showTour), panel toggles (pluginsEnabled, gitopsEnabled, networkEnabled), unified log pod selection (unifiedLogsSelectedPods)
    resourceSliceAll 28 resource arrays, section loading with 30s TTL + module-level inFlightSections deduplication guard, dashboard fetch, resource navigation
    operationSliceScale/delete/YAML modals, exec session management, port-forward state
    analysisSliceSecurity scanning (kubesec + trivy), scanInBackground state for background scans, owner chain, debug pods, Prometheus config
    providersSliceIstio/Traefik/NGINX provider detection state
    krewSliceKrew availability detection, curated plugin index (installed status), install/uninstall actions
    • Component Orchestration: The root App.tsx acts as a high-level shell. UI complexity is delegated to:
    ComponentResponsibility
    LayoutStructural shell (Sidebar, Production banners, Sidecar alerts)
    SectionRouterRouting 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
    OverlayManagerFloating terminals, YAML editors, and global modals
    ErrorBoundaryDeclarative error recovery for critical UI zones
    • Talks to the sidecar via plain fetch() through IPC helpers (checkedSidecarFetch in src/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.

    PackageResponsibility
    cmd/podscape-core/main.goRoute 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:

    ValueMeaning
    nilProbe not yet run or failed — all resources treated as allowed (permissive)
    empty map {}All resources denied
    populated mapProbed 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.

    APIChannelDirection
    window.sidecar.onCrashed(cb)sidecar:crashedMain → Renderer
    window.sidecar.restart()sidecar:restartRenderer → Main

    Main Process (src/main/)

    FileResponsibility
    index.tsApp bootstrap, splash window, sidecar start, BrowserWindow creation
    sidecar/sidecar.tsLaunch / monitor / kill the Go subprocess; expose sidecar:restart IPC
    sidecar/api.tscheckedSidecarFetch — injects token, retries up to 20× with 500 ms delay
    sidecar/auth.tsGenerates the random per-session X-Podscape-Token
    sidecar/runtime.tsShared activeSidecarPort variable
    ipc/kubectl.tsIPC handlers for log streaming, port-forward, file copy, owner chain, metrics
    ipc/terminal.tsPTY terminal sessions via node-pty
    ipc/helm.tsHelm IPC handlers — repo browser, SSE install relay
    ipc/settings.tsSettings IPC handlers
    ipc/dialog.tsNative file open/save dialogs
    settings/settings_storage.tsRead / write ~/.podscape/settings.json
    system/env.tsAugments subprocess PATH for cloud credential helpers
    system/updater.tsAuto-updater checks and notifications
    system/kubeProvider.tsKubeconfig 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):

    FieldTypeDescription
    prodContextsstring[]List of context names treated as production
    isProductionbooleanDerived: true when selectedContext is included in prodContexts
    setProdContexts(contexts)async actionUpdates 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> gains ring-inset ring-4 ring-red-500/50 when isProduction is 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:

    NamespacePurpose
    window.kubectlAll k8s operations, port-forward, log streaming, file copy, owner chain, Prometheus queries + prometheusFlushCache
    window.helmHelm release operations and repo browser
    window.execPTY exec-into-container sessions
    window.settingsRead / write app settings
    window.kubeconfigKubeconfig file path selection
    window.dialogNative file open/save dialogs
    window.sidecarSidecar 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:

    ProviderDetection method
    Istionetworking.istio.io API group present
    Traefik v3traefik.io API group present
    Traefik v2traefik.containo.us API group present
    NGINX Inck8s.nginx.org API group present
    NGINX CommunityIngressClass 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

    Rendering diagram…

    Application Security

    Electron hardening

    SettingValueEffect
    nodeIntegrationfalseRenderer cannot access Node.js APIs
    contextIsolationtruePreload and renderer run in separate JS contexts
    sandboxtrueRenderer process is OS-sandboxed
    setWindowOpenHandlerdeny + openExternalNew 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:

    PackageReason
    dompurify ≥ 3.4.0mXSS, prototype pollution, ADD_ATTR bypass fixes
    @xmldom/xmldom ^0.8.12XML parser security fixes
    lodash ^4.18.1Prototype pollution
    brace-expansion ^1.1.13 / ^2.0.3ReDoS

    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.Mutex inside the wsStream.Write helper.
    • 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:

    typescript
    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'
    PreviousOverviewNext Features Guide
    Podscape Docs
    3 of 8

    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

    PlatformShortcut
    macOS⌘K
    Windows / LinuxCtrl+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 section identifier itself (e.g. "unifiedlogs")
    • The .metadata.name field of every loaded resource across all 27 resource types

    Example queries

    QueryWhat it finds
    nginx-apiAny pod, deployment, or service whose name contains nginx-api
    batchNavigates to Jobs or CronJobs sections
    scanNavigates to Security Hub
    certNavigates to TLS Certificates
    pingNavigates to Connectivity Tester
    my-postgresOpens 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:

    1. A red "PRODUCTION CONTEXT ACTIVE" banner drops down from the top-center of the window.
    2. 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

    1. Open Settings (sidebar, bottom of the left navigation, or search "settings" in the Command Palette).
    2. Find the Production Contexts field.
    3. Enter the names of your production kubeconfig contexts, one per line or comma-separated.
    4. Save. The setting is stored in ~/.podscape/settings.json under the prodContexts key 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

    1. 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.
    2. Click a pod in the dropdown to add it to the active stream list. You can add as many pods as you need.
    3. 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

    ModeWhen to use
    DiagnoseAutomated step-by-step DNS → TCP → HTTP test between a source pod and a target service or pod
    ManualRun 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:

    1. DNS Resolution — runs nslookup against the target hostname inside the source pod to verify the cluster DNS can resolve the name.
    2. TCP Port Check — runs nc -zv to confirm the target's TCP port is reachable.
    3. HTTP Response — runs curl with 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:

    1. Select Source pod: frontend-abc123 (namespace: prod)
    2. Set Target: api-service.prod.svc.cluster.local, port 8080, path /health
    3. Click Run Diagnosis
    4. Step 1 (DNS) passes in 12ms. Step 2 (TCP) fails after 5000ms.
    5. Click Investigate Failure — the analysis shows a NetworkPolicy deny-external-ingress in the prod namespace 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:

    CommandUse case
    curlTest HTTP/HTTPS endpoints, check response codes, inspect headers
    ncCheck raw TCP port reachability
    pingVerify 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.

    1. Navigate to the CronJobs section.
    2. Open a CronJob detail view.
    3. 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.

    StatusMeaning
    Update availableA newer version was found in a configured repository. A glowing blue badge shows the version number.
    Latest versionYour release is already running the most recent version available in the repos.
    Local / Custom ChartThe 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.

    1. Clicking Upgrade fetches your current configuration values.
    2. A YAML editor opens, pre-filled with your existing overrides.
    3. 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:

    ConditionWhat it means
    OOMKilledThe 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 codeThe 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 eventsLiveness or readiness probe failures that caused a restart. The analyzer surfaces the probe failure message from the cluster event stream.
    CrashLoopBackOffThe 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 Pending or CrashLoopBackOff and 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 ← CRDs breadcrumb 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:

    ColumnNotes
    NameResource name in monospace
    NamespaceShown only when viewing all namespaces
    AgeTime 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:

    SectionSummary column
    Virtual ServicesTotal HTTP + TCP route count
    Destination RulesHost
    GatewaysServer count
    Service EntriesLocation (MESH_INTERNAL / MESH_EXTERNAL)
    Peer AuthenticationmTLS mode
    IngressRoutes (Traefik)Entry points
    MiddlewaresType
    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

    TabShows
    InstalledPlugins from the curated list that are currently installed on your machine
    BrowseAll curated plugins, installed or not

    Plugins installed via kubectl krew install that 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.

    1. Switch to the Browse tab.
    2. Click any plugin row to open its Info view.
    3. Click Install. Podscape runs kubectl krew install <plugin> in the background.
    4. Once installed, the Run tab becomes available.

    Running a plugin

    1. Click any installed plugin row (or switch to the Run tab from the Info view).
    2. Fill in the inputs (namespace, resource name, etc.) and click Run.
    3. 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.

    PluginWhat it doesAuthor
    neatStrips managed fields and defaults from manifests to make them human-readable@itaysk
    sternTails logs from multiple pods simultaneously with regex filteringstern/stern
    treeVisualises Kubernetes object ownership hierarchies@ahmetb
    imagesLists all container images running in the cluster@chenjiandongx
    whoamiShows the currently authenticated subject@rajatjindal
    df-pvReports disk usage for PersistentVolumeClaims@yashbhutwala
    outdatedFinds container images running outdated versionsreplicatedhq

    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.

    PreviousArchitectureNext MCP Server
    Podscape Docs
    4 of 8

    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-mcp talks 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):

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

    macOS (Intel):

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

    Linux (amd64):

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

    Windows (amd64): Download podscape-mcp-windows-amd64.exe from the release page and place it somewhere on your PATH.

    Option B — Build from source

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

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

    After adding, start a new Claude Code session — MCP servers connect on startup:

    bash
    claude

    Verify 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):

    json
    1{
    2  "mcpServers": {
    3    "podscape": {
    4      "command": "/usr/local/bin/podscape-mcp",
    5      "args": []
    6    }
    7  }
    8}

    To use a non-default kubeconfig:

    json
    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):

    json
    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

    FlagDefaultDescription
    --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.

    ToolPreview shows
    delete_resourceKind, name, and namespace that would be deleted
    drain_nodeExact pod list that would be evicted vs skipped (capped at 50)
    helm_uninstallRelease 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.

    ParameterTypeRequiredDescription
    resourcestringyesResource type: pods, deployments, services, nodes, configmaps, secrets, custom CRD plural names (e.g. virtualservices, ingressroutes), etc.
    namespacestringnoNamespace filter; omit for all namespaces
    label_selectorstringnoLabel selector, e.g. app=nginx or env=prod,tier=frontend
    field_selectorstringnoField selector, e.g. status.phase=Running or spec.nodeName=node-1
    limitnumbernoMax 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.

    ParameterTypeRequiredDescription
    resourcestringyesResource type
    namestringyesResource name
    namespacestringnoNamespace; 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.

    ParameterTypeRequiredDescription
    resourcestringyesResource type
    namestringyesResource name
    namespacestringnoNamespace; 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.

    ParameterTypeRequiredDescription
    podstringyesPod name
    namespacestringyesNamespace
    containerstringnoContainer name (defaults to first container)
    tailnumbernoNumber of lines (default 100); ignored when since_minutes is set
    since_minutesnumbernoReturn logs from the last N minutes (overrides tail)
    previousbooleannoFetch logs from the previously terminated container instance (useful for crash-looping pods)
    init_containerbooleannoWhen true, fetches logs from init containers instead of main containers

    list_events

    List Kubernetes events sorted by most recent first.

    ParameterTypeRequiredDescription
    namespacestringnoNamespace filter; omit for all namespaces
    typestringnoWarning or Normal; omit for all types
    object_namestringnoFilter events for a specific object name
    limitnumbernoMax 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:

    json
    {
      "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.

    ParameterTypeRequiredDescription
    namespacestringnoNamespace filter; omit for all namespaces

    helm_status

    Get the full status output of a Helm release.

    ParameterTypeRequiredDescription
    releasestringyesRelease name
    namespacestringyesNamespace

    helm_values

    Get the values of a Helm release.

    ParameterTypeRequiredDescription
    releasestringyesRelease name
    namespacestringyesNamespace
    allbooleannoInclude computed/default values (equivalent to helm get values --all)

    helm_history

    List all revisions of a Helm release.

    ParameterTypeRequiredDescription
    releasestringyesRelease name
    namespacestringyesNamespace

    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
    • allowPrivilegeEscalation not explicitly set to false
    • readOnlyRootFilesystem not set to true
    • Dangerous capabilities present: NET_ADMIN, SYS_ADMIN, SYS_PTRACE, ALL
    ParameterTypeRequiredDescription
    namespacestringyesNamespace 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.

    ParameterTypeRequiredDescription
    groupstringnoFilter 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.

    ParameterTypeRequiredDescription
    kindstringyespods or nodes
    namespacestringnoNamespace 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.

    ParameterTypeRequiredDescription
    podstringyesPod name
    namespacestringyesNamespace
    tailnumbernoLog lines per container (default 50)
    previousbooleannoFetch 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.

    ParameterTypeRequiredDescription
    namespacestringnoNamespace filter; omit for all namespaces

    get_resource_events

    Get Kubernetes events for a specific named resource — equivalent to the Events section of kubectl describe.

    ParameterTypeRequiredDescription
    kindstringyesResource kind, e.g. Pod, Deployment, Node, Service
    namestringyesResource name
    namespacestringnoNamespace; 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.

    ParameterTypeRequiredDescription
    resourcestringyesResource type (plural), e.g. pods, deployments, services
    namestringyesResource name
    namespacestringnoNamespace; 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.

    ParameterTypeRequiredDescription
    kindstringyesdeployment or statefulset
    namestringyesResource name
    namespacestringyesNamespace
    replicasnumberyesDesired replica count (must be >= 0)

    delete_resource

    Delete a Kubernetes resource. Requires confirm=true to execute — call without it first to see a preview.

    ParameterTypeRequiredDescription
    kindstringyesResource kind, e.g. pod, deployment, service
    namestringyesResource name
    namespacestringyesNamespace
    confirmbooleannoMust 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.

    ParameterTypeRequiredDescription
    kindstringyesdeployment, daemonset, or statefulset
    namestringyesResource name
    namespacestringyesNamespace

    rollout_undo

    Roll back a deployment to a previous revision.

    ParameterTypeRequiredDescription
    kindstringyesdeployment (currently the only supported kind)
    namestringyesResource name
    namespacestringyesNamespace
    revisionnumbernoTarget 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.

    ParameterTypeRequiredDescription
    yamlstringyesThe full YAML manifest content

    cordon_node

    Cordon or uncordon a node to prevent or allow new pod scheduling.

    ParameterTypeRequiredDescription
    namestringyesNode name
    unschedulablebooleanyestrue = 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.

    ParameterTypeRequiredDescription
    namestringyesNode name
    forcebooleannoDelete pods not managed by a controller (default false)
    ignore_daemonsetsbooleannoSkip DaemonSet-managed pods (default true)
    delete_emptydir_databooleannoAllow eviction of pods with emptyDir volumes (default false)
    confirmbooleannoMust be true to drain. Omit or set false to preview which pods would be evicted.

    Preview response (without confirm=true):

    json
    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>.

    ParameterTypeRequiredDescription
    namestringyesCronJob name
    namespacestringyesNamespace

    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).

    ParameterTypeRequiredDescription
    podstringyesPod name
    namespacestringyesNamespace
    containerstringnoContainer name (defaults to first container)
    commandarrayyesCommand 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.

    ParameterTypeRequiredDescription
    contextstringyesKubernetes 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.

    ParameterTypeRequiredDescription
    releasestringyesRelease name
    namespacestringyesNamespace
    revisionnumbernoTarget 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).

    ParameterTypeRequiredDescription
    releasestringyesRelease name
    namespacestringyesNamespace
    chartstringyesChart reference: local path, repo/chart, or OCI reference
    valuesstringnoOptional 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.

    ParameterTypeRequiredDescription
    releasestringyesRelease name
    namespacestringyesNamespace
    confirmbooleannoMust 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).

    ParameterTypeRequiredDescription
    releasestringyesRelease name
    namespacestringyesNamespace

    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:

    1. list_failing_pods with namespace=production to find the pod
    2. pod_summary with 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:

    1. cluster_health to get node/pod counts and recent Warning events
    2. Optionally list_failing_pods for 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:

    1. Call drain_node with name=node-3 (no confirm) — receives the pod preview
    2. Present the preview to you for confirmation
    3. Call drain_node again with confirm=true to 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:

    1. describe_resource with resource=pods, name=api-server — gets the pod spec and events in one call
    2. get_pod_logs with init_container=true to 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:

    1. list_contexts to see available contexts
    2. switch_context with the staging context name
    3. 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:

    1. helm_status with release=checkout-service to confirm the current state
    2. helm_history to see available revisions
    3. helm_rollback with release=checkout-service and revision=0
    4. helm_status again 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:

    bash
    kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

    MCP 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.

    PreviousFeatures GuideNext API Reference
    Podscape Docs
    5 of 8

    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

    MethodPathDescription
    GET/healthReturns 200 OK when informers are synced (or in no-kubeconfig mode). Returns 503 while syncing. No auth required.

    Workloads

    MethodPathDescription
    GET/nodesAll cluster nodes
    GET/namespacesAll namespaces
    GET/podsPods (filter with ?namespace=)
    GET/deploymentsDeployments
    GET/daemonsetsDaemonSets
    GET/statefulsetsStatefulSets
    GET/replicasetsReplicaSets
    GET/jobsJobs
    GET/cronjobsCronJobs
    GET/hpasHorizontalPodAutoscalers
    GET/pdbsPodDisruptionBudgets

    Networking

    MethodPathDescription
    GET/servicesServices
    GET/ingressesIngresses
    GET/ingressclassesIngressClasses
    GET/networkpoliciesNetworkPolicies
    GET/endpointsEndpoints

    Config & Storage

    MethodPathDescription
    GET/configmapsConfigMaps
    GET/secretsSecrets (values masked server-side)
    GET/pvcsPersistentVolumeClaims
    GET/pvsPersistentVolumes
    GET/storageclassesStorageClasses

    RBAC

    MethodPathDescription
    GET/serviceaccountsServiceAccounts
    GET/rolesRoles
    GET/clusterrolesClusterRoles
    GET/rolebindingsRoleBindings
    GET/clusterrolebindingsClusterRoleBindings
    GET/crdsCustomResourceDefinitions
    GET/eventsEvents

    Kubernetes Operations

    MethodPathBody / ParamsDescription
    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/applyRaw YAML bodyApply 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

    MethodPathBody / ParamsDescription
    POST/node/cordon?name=&unschedulable=Cordon (true) or uncordon (false) a node
    POST/node/drain?name=Drain a node (cordon + pod eviction)

    CronJob Operations

    MethodPathBody / ParamsDescription
    POST/cronjob/trigger?namespace=&name=Create a Job from a CronJob manually

    Context Management

    MethodPathDescription
    GET/config/contextsList all kubeconfig contexts
    GET/config/current-contextActive context name
    POST/config/switchSwitch active context {context}

    Metrics

    MethodPathDescription
    GET/metrics/podsPod CPU / memory (requires metrics-server)
    GET/metrics/nodesNode CPU / memory (requires metrics-server)

    Prometheus

    MethodPathDescription
    GET/prometheus/statusAuto-discover Prometheus via k8s service proxy or manual URL
    POST/prometheus/query_range_batchBatch PromQL range queries — 60s TTL cache + singleflight deduplication per query
    POST/prometheus/cache/clearEvict all cached Prometheus results (called on context switch and manual refresh)

    Batch request body:

    json
    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:

    json
    [
      { "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

    MethodPathDescription
    GET/helm/listInstalled Helm releases
    GET/helm/statusRelease status ?name=&namespace=
    GET/helm/valuesRelease values ?name=&namespace=
    GET/helm/historyRelease history ?name=&namespace=
    POST/helm/rollbackRoll back a release
    POST/helm/upgrade?name=&namespace=&chart=&version=
    POST/helm/uninstallUninstall a release
    GET/helm/reposList configured Helm repositories
    GET/helm/repos/searchSearch charts ?q=&repo=&limit=&offset=
    GET/helm/repos/versionsChart versions ?chart=&repo=
    GET/helm/repos/valuesDefault values for a chart version
    POST/helm/repos/refreshRe-fetch repo indexes (SSE stream)
    POST/helm/installInstall a chart (SSE stream)

    Install body:

    json
    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

    MethodPathDescription
    GET/providersDetect installed service mesh and ingress providers (Istio, Traefik v2/v3, NGINX Inc, NGINX Community)

    Response:

    json
    1{
    2  "istio": true,
    3  "traefikV3": false,
    4  "traefikV2": false,
    5  "nginxInc": false,
    6  "nginxCommunity": true
    7}

    Detection methods:

    • 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

    Custom Resources

    MethodPathDescription
    GET/customresourceList 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

    MethodPathDescription
    GET/owner-chainTraverses owner references up (ancestors) and down (descendants)

    Query params: ?kind=Pod&name=my-pod&namespace=default

    Response:

    json
    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

    MethodPathDescription
    POST/security/scanFull audit: engine + Trivy + Kubesec (SSE stream)
    POST/security/kubesecSingle resource Kubesec audit
    POST/security/kubesec/batchBatch Kubesec audit (worker pool, 8 concurrent)
    POST/security/trivy/imagesTrivy image scan for selected images (SSE stream)

    SSE events (for streaming endpoints):

    • progress — real-time log lines
    • result — final JSON payload
    • error — error message

    Topology

    MethodPathDescription
    GET/topologyCluster topology graph (nodes → pods → services)

    TLS Certificates

    MethodPathDescription
    GET/tls-certsCluster-wide certificate inventory with expiry tracking

    GitOps

    MethodPathDescription
    GET/gitopsArgo CD / Flux resource overview
    POST/gitops/reconcile{kind, name, namespace}
    POST/gitops/suspend{kind, name, namespace, suspend}

    Debug Pod

    MethodPathDescription
    POST/debugpod/createLaunch an ephemeral debug pod on a specified node

    Port Forward

    MethodPathDescription
    POST/stopPortForward?id= — stop an active port-forward tunnel
    WS/portforwardPort-forward lifecycle events (ready / error / exit)

    Real-time (WebSocket)

    PathDescription
    ws://127.0.0.1:5050/logsReal-time container log stream
    ws://127.0.0.1:5050/execInteractive PTY exec into a container
    ws://127.0.0.1:5050/portforwardPort-forward lifecycle events (ready / error / exit)
    PreviousMCP ServerNext Security Hub
    Podscape Docs
    6 of 8

    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):

    RuleCheck
    Missing Resource LimitsContainers without CPU or Memory limits
    Latest Image TagContainers using the :latest tag
    Missing Liveness ProbeContainers without a liveness probe
    Missing Readiness ProbeContainers without a readiness probe
    Sensitive Env VariablePlain-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), and info (> 3) levels.

    3. Dynamic Image Vulnerability Scanning — Trivy

    • Engine: Aqua Security Trivy — invoked via os/exec from 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 (progress events) and the final report (result event) are streamed in real-time. The sidecar compacts Trivy's pretty-printed JSON with json.Compact before 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:

    1. Click the ▾ arrow next to the Full Scan button and choose Run in Background.
    2. 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.
    3. 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

    FeatureDescription
    Flat / grouped viewToggle between a flat resource list and grouping by namespace
    System filterAuto-hides kube-system, kube-node-lease, cert-manager, and Node resources; toggle "Show System" to reveal
    Colored kind badgesEvery row shows a colored pill (Deployment, StatefulSet, DaemonSet, etc.) for instant resource-type identification
    Config / CVE panelsExpanded rows display a red "Configuration Issues" card and an orange "Image Vulnerabilities" card separately
    CVE detailEach vulnerability shows the image name, package name, fix version, CVE ID, and severity
    Severity filter tabsFilter results to Critical-only or Warning-only
    Sortable columnsSort by resource name, namespace, kind, config issues, CVE count, or combined score
    Navigate to resourceClick the ↗ button on any row to open that resource's detail panel directly
    ExportDownload filtered results as CSV or JSON for external reporting

    Score Model

    Each resource in the table receives a combined risk score:

    ScoreIndicatorCondition
    2 — CriticalRed dotHas CRITICAL or HIGH CVEs from Trivy
    1 — WarningAmber dotHas config issues from the engine or Kubesec
    0 — OKGrey dotNo 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:

    1. Switches the active section in the left sidebar to the resource's kind (e.g. Pods, Deployments).
    2. Loads the resource list for that section.
    3. 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.
    PreviousAPI ReferenceNext Keyboard Shortcuts
    Podscape Docs
    7 of 8

    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 and Ctrl on Windows/Linux.

    Global Shortcuts

    These shortcuts are active anywhere in the application, regardless of which section is open.

    ShortcutPlatformAction
    ⌘ KmacOSOpen / close the Command Palette
    Ctrl KWindows / LinuxOpen / 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)

    KeyAction
    Type to searchFilter sections and resources by name or keyword
    ↓ Arrow DownMove selection down through results
    ↑ Arrow UpMove selection up through results
    EnterJump to the selected section or open the selected resource
    EscapeClose the palette without navigating

    How search works

    The palette searches two pools simultaneously:

    1. 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.
    2. Resources — matched against the metadata.name of 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 LabelInternal IDSearch Keywords
    Dashboarddashboardhome, overview
    Podspodsworkload
    Deploymentsdeploymentsworkload
    DaemonSetsdaemonsetsworkload
    StatefulSetsstatefulsetsworkload
    ReplicaSetsreplicasetsworkload
    Jobsjobsworkload, batch
    CronJobscronjobsworkload, batch, schedule
    HPAshpasautoscaling, scale
    PodDisruptionBudgetspdbspdb, disruption
    Servicesservicesnetwork, svc
    Ingressesingressesnetwork, routing
    Ingress Classesingressclassesnetwork
    Network Policiesnetworkpoliciesnetwork, policy
    Endpointsendpointsnetwork
    ConfigMapsconfigmapsconfig, cm
    Secretssecretsconfig, credentials
    PVCspvcsstorage, volume, persistent
    PVspvsstorage, volume, persistent
    Storage Classesstorageclassesstorage
    Service Accountsserviceaccountsrbac, auth
    Rolesrolesrbac, auth, permission
    Cluster Rolesclusterrolesrbac, auth
    Role Bindingsrolebindingsrbac, auth
    Cluster Role Bindingsclusterrolebindingsrbac, auth
    Nodesnodescluster, infrastructure
    Namespacesnamespacescluster
    CRDscrdscluster, custom, resources
    Eventseventsobserve, logs, warning
    Metricsmetricsobserve, cpu, memory, usage
    Unified Logsunifiedlogsobserve, logs, stream
    Port Forwardsportforwardsnetwork, tunnel, forward
    Network Mapnetworktopology, visualize
    Connectivityconnectivitytest, ping, curl
    Debug Podsdebugpoddebug, shell, exec
    Security Hubsecurityscan, trivy, kubesec, vulnerability
    TLS Certificatestlscert, ssl, x509, expiry
    GitOpsgitopsflux, argo, argocd, kustomize, gitops
    Helm Chartshelmhelm, releases, charts, package
    Settingssettingsconfig, 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.

    KeyAction
    EscapeClose 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
    DeleteOpen 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
    BackspaceSame 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.

    ShortcutPlatformAction
    ⌘ TmacOSOpen an interactive shell (exec) into the selected container
    Ctrl TWindows / LinuxOpen an interactive shell (exec) into the selected container
    ⌘ LmacOSSwitch to the Logs tab and enter fullscreen log view
    Ctrl LWindows / LinuxSwitch to the Logs tab and enter fullscreen log view
    ⌘ DmacOSClose fullscreen log view (only when log fullscreen is active)
    Ctrl DWindows / LinuxClose fullscreen log view (only when log fullscreen is active)
    EscapeAllClose 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.

    ShortcutPlatformAction
    ⌘ DmacOSClose the exec panel (only fires when focus is not in an input or textarea)
    Ctrl DWindows / LinuxClose the exec panel (only fires when focus is not in an input or textarea)
    EscapeAllClose the exec panel (only when the file-transfer sub-panel is not open)
    TabAllSent to the PTY as a tab-completion character (browser focus-navigation is suppressed)
    Enter (in path input)AllSubmit 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.

    ShortcutPlatformAction
    ⌘ EntermacOSRun the connectivity test (when the form is valid and ready to run)
    Ctrl EnterWindows / LinuxRun 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:

    KeyAction
    EnterConfirm and execute the deletion (only when the typed name matches the resource name)

    Notes

    • All ⌘/Ctrl shortcuts use e.metaKey on macOS and e.ctrlKey on Windows/Linux — this is detected automatically via src/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.
    PreviousSecurity HubNext Troubleshooting
    Podscape Docs
    8 of 8

    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:

    1. Check the binary exists. In development:

      bash
      ls go-core/podscape-core

      If it is missing, build it:

      bash
      cd go-core && go build ./cmd/podscape-core/

      In production, the binary is bundled at resources/bin/podscape-core inside the app package.

    2. Check executable permissions (macOS/Linux). The app applies chmod 755 automatically, but if you copied the binary manually it may lack execute permission:

      bash
      chmod +x go-core/podscape-core
    3. Check port 5050. See Port 5050 Already In Use below.

    4. 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:

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

    1. Click Reconnect. This calls sidecar:restart over IPC, which relaunches the binary and reloads the renderer once the sidecar is healthy again.
    2. If the sidecar keeps crashing, open the system console (macOS: Console.app, Linux: journalctl) and look for crash reports from podscape-core.
    3. 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:

    1. Open the Metrics section to confirm the cluster API server is reachable at all.
    2. Check your VPN connection if the cluster is remote.
    3. Try switching to a different context and back — this triggers a full context switch which re-initialises the sidecar's clientset and informers.
    4. 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.
    5. 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:

    bash
    1# macOS / Linux
    2lsof -i :5050
    3kill <PID>
    4
    5# Windows
    6netstat -ano | findstr :5050
    7taskkill /PID <PID> /F

    Then 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:

    1. Ensure ~/.kube/config exists and is readable:
      bash
      cat ~/.kube/config
    2. If your kubeconfig is at a non-standard path, set the KUBECONFIG environment variable before launching:
      bash
      KUBECONFIG=/path/to/my/kubeconfig open /Applications/Podscape.app
    3. Use the onboarding screen's file picker to browse to your kubeconfig.
    4. 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:

    1. Check that the cluster API endpoint is reachable from your machine:
      bash
      kubectl --context=<context-name> cluster-info
    2. 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>
    3. Check VPN status for private clusters.
    4. 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:

    1. Verify with kubectl directly:
      bash
      kubectl --context=<context-name> get nodes
    2. Check the RBAC section below if lists show the amber "Access denied" banner instead of errors.
    3. 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:

    OutcomeBehaviour
    SAR API unavailable (error)All informers start unconditionally (pre-RBAC permissive mode)
    Resource explicitly deniedInformer skipped; handler returns 200 [] + X-Podscape-Denied: true
    Resource allowedInformer 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:

    1. 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>
    2. Both must return yes for Podscape to serve the section.
    3. 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] probe messages.
    4. 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:

    bash
    # Stop with Ctrl+C, then:
    npm run dev

    A 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:

    bash
    chmod +x node_modules/node-pty/prebuilds/darwin-*/spawn-helper

    If you are on an M-series Mac and see darwin-arm64:

    bash
    chmod +x node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper

    After 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:

    bash
    cd go-core && go build ./cmd/podscape-core/
    cd ..
    npm run dev

    After 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:

    1. Check your internet connection and any proxy settings.
    2. Wait a few minutes and use Check for Updates in Settings to retry.
    3. 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:

    1. Download the latest installer from GitHub Releases and run it directly. This bypasses the in-app updater entirely.
    2. On macOS, if the app is in a read-only location (e.g., mounted DMG), move it to /Applications before 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:

    1. Use the namespace filter — switching from "All Namespaces" to a specific namespace dramatically reduces the number of resources loaded into the renderer.
    2. 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.
    3. 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:

    1. Use the container filter in the pod detail panel to stream only the relevant container rather than all containers simultaneously.
    2. Open a terminal session (Multi-Terminal section) and use kubectl logs --since=1m -f <pod> with grep to filter server-side before the output reaches the UI.
    3. 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:

    1. Ensure Trivy is installed and its database is up to date:
      bash
      trivy image --download-db-only
    2. Run the scan in a namespace with fewer workloads first to verify Trivy is working correctly before scanning the whole cluster.
    3. 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.
    PreviousKeyboard Shortcuts
    On this page
    All pages
    OverviewArchitectureFeatures GuideMCP ServerAPI ReferenceSecurity HubKeyboard ShortcutsTroubleshooting