The Problem
Kubernetes users need a native desktop UI that works offline, integrates with local tooling (kubectl, kubeconfig) and runs consistently on macOS, Windows, and Linux. Existing options are either cloud‑only, require a browser, or are tied to a specific distribution, forcing teams to juggle separate CLI workflows.
What This Does
freelens ships an Electron‑based IDE that bundles the UI, a minimal Node backend, and platform‑specific installers (see freelens/build/.sh, freelens/electron-builder.yml). The main process starts from freelens/src/main/index.ts, registers injectables, and launches the renderer defined in freelens/src/renderer/index.ts. Webpack builds for both processes are driven by freelens/webpack/main.ts and freelens/webpack/renderer.ts.
Feature modules live under packages/ and are wired through the DI system: Keyboard shortcuts – packages/business-features/keyboard-shortcuts/index.ts Cluster settings – packages/cluster-settings/index.ts Sidebar UI – packages/cluster-sidebar/src/sidebar-items.injectable.ts
All UI code is TypeScript/React (e.g., packages/cluster-sidebar/src/feature.tsx), and the project is monorepo‑managed with pnpm (pnpm-lock.yaml at the root and in freelens/).
How To Use It
Setup
Install pnpm if not present npm i -g pnpm Install workspace dependencies pnpm install Build the Electron app (script defined in root package.json) pnpm run build # runs webpack and packages the binaries
The package.json files in the root, freelens/, and each package contain the necessary scripts; the exact names can be confirmed with pnpm run.
Configuration
Kubeconfig location is read from the standard $HOME/.kube/config unless overridden by the environment variable KUBECONFIG (handled in packages/core/src/common/app-paths/directory-for-kube-configs). Binary paths for kubectl and helm are resolved by the injectables in packages/core/src/common/app-paths/directory-for-kubectl-binaries. No additional config files are required for a default install.
Running
After a successful build, the packaged binary can be launched directly (./dist/freelens on macOS/Linux, Freelens.exe on Windows) or via the generated installers (.dmg, .deb, .rpm). For development, start the hot‑reloaded UI with: pnpm run start # runs webpack dev server (see freelens/webpack/dev-server.ts)
Real‑World Use
A CI pipeline can provision a temporary Kind cluster, then invoke the app in headless mode for automated UI tests: import { createCluster } from './freelens/integration/helpers/kind'; await createCluster('test-cluster'); await page.goto('app://-'); // Playwright script against the Electron renderer
The integration test suite (freelens/integration/tests/.tests.ts) already demonstrates this pattern.
Code Health & Issues
Low – No explicit linting failures – biome.jsonc and GitHub Actions (.github/workflows/biome-migrate.yaml) enforce formatting. Low – Test coverage present – 17 Jest test files across core and feature packages, plus integration tests. Medium – Dependency duplication – Separate package.json files in each package may cause version drift; lockfile is only at the workspace root (pnpm-lock.yaml). Low – Platform‑specific scripts – Build scripts for Debian (freelens/build/apt/.list) assume apt availability; Windows/macOS equivalents are present, but CI does not test all three platforms in a single workflow. Low – Limited runtime error handling – Some injectables (e.g., directory-for-kubectl-binaries) assume binaries exist; missing binaries will surface as uncaught errors at startup. None – License & CI – MIT license present, CI pipelines cover unit, integration, security scanning, and Trunk checks.
The Bottom Line
freelens provides a well‑structured, Electron‑based Kubernetes UI with a clear modular architecture and solid test coverage. It is ready for internal deployment or small‑team use, though teams should monitor dependency versions across packages and verify binary availability on target hosts. If you need a self‑contained desktop IDE for Kubernetes without vendor lock‑in, this repo is a practical starting point.