Skip to main content
Lumovi is open source under the Apache 2.0 license, on GitHub. It’s written in TypeScript: an Electron app with a React interface, a small Node.js server for running it in a cluster, and an agent for a fleet’s private clusters.

Build the app

You need Node.js 24 or later (the repository’s .nvmrc asks for 26) and npm. The desktop app’s terminals run on node-pty, which is native code. On macOS and Windows it comes prebuilt. On Linux, npm ci builds it, so you also need Python 3, make and a C++ compiler (sudo apt-get install python3 make g++ on Debian and Ubuntu). After installing, scripts/node-pty.ts makes node-pty’s spawn-helper executable: its package comes without that, and on macOS, terminals can’t start without it. To package the app, you also need:
  • On a Mac: Xcode 26 or later. Lumovi’s icon is compiled by Xcode’s actool, and packaging stops without it.
  • On Linux: rpm, to build the .rpm (sudo apt-get install rpm on Debian and Ubuntu).
1

Get the code

2

Build the installers

It downloads helm 4.3.0 from get.helm.sh for each installer, checked against the SHA-256 pinned in scripts/helm.ts, for the app to ship with. The installers for your platform land in release/, for x64 and arm64: a .dmg and .zip on macOS, one .exe on Windows, and an AppImage, .deb and .rpm on Linux. npm run package builds an unpacked app there instead, which is quicker.On Linux, node-pty is built for the computer it’s installed on, so build only for that computer’s architecture: npm run dist -- --x64, or npm run dist -- --arm64 on an ARM one. An installer for the other architecture would carry a node-pty that can’t run there. Lumovi’s own releases build each on a machine of that architecture.
A copy you build yourself isn’t signed or notarized. For everyday use, the official releases are signed on macOS and Windows, and come with checksums and provenance.The installers npm run dist makes look for new versions the way the official ones do, on Lumovi’s GitHub releases. To keep running your own build, turn off Help → Check for Updates Automatically. An app from npm run package can’t update itself.

Run it while you work on it

dev and dev:mock reload as you change the code. They run the helm on your login shell’s PATH for Helm actions, as there’s no helm shipped with them: install Helm, or set LUMOVI_HELM, to try those. The demo clusters are the ones the tests use: a busy one with every kind of problem, an empty one without metrics, one with 2,500 pods, and contexts that fail in every way a real one can. dev:server builds Lumovi and serves it at http://127.0.0.1:8080, and prints the demo tokens to sign in with. With -- --fleet, it serves a fleet of the demo clusters instead, and one that never answers, with a mock single sign-on: sign in, and you’re Alice, a developer.
The app can change clusters. Try your work against the demo clusters or a local kind cluster, not production. LUMOVI_READ_ONLY=1 npm run dev keeps every cluster read-only.

Commands

npm run build bundles a fleet’s agent on its own, with vite.agent.config.ts, into out/agent/agent.js. The image carries it next to the server, for the chart’s mode: agent to run, and the desktop app leaves it out.

How it’s built

src
main
backend
server
preload
renderer
shared
charts
tests
e2e
web
plugins
mock-cluster
mock-oidc
integration
docs
build
scripts
A few ideas hold it together:
  • One page, two hosts. The interface talks to its host through one typed API: over IPC in the desktop app, over a WebSocket when served. Both answer from the same handlers. What only one can do, like port forwards and terminals on the desktop or sessions on the server, is an optional part of that API, which the page shows only when it’s there.
  • Credentials stay in the main process, the only place that talks to clusters. The page runs sandboxed, with context isolation, no Node.js access and a strict Content Security Policy, and every IPC call is checked for its sender and validated there. The page sees a kubeconfig only while you paste one to add a cluster, and it can open a terminal, your own shell: it isn’t a wall between your files and itself. See Your credentials.
  • Plain REST. Authentication comes from @kubernetes/client-node, and requests are plain REST calls with gzip, so any API path, metrics and logs included, works the same way.
  • Status colors are for health. They always come with an icon and a label, and charts use a palette checked for color blindness in both themes.

Tests

Lumovi keeps above 90% end-to-end coverage of statements, branches, functions and lines, with every source file loaded by some test, enforced in CI. New code comes with tests that run it.
  • End-to-end tests drive the real Electron app with Playwright, against a mock API server with the demo clusters. Coverage is collected from all three Electron processes, the server and the page, and merged across Linux, macOS and Windows. The test windows stay invisible and never take focus, so you can keep working; set LUMOVI_E2E_FOREGROUND=1 to watch them.
  • Web tests start the server against the same mock clusters and a mock OpenID Connect provider, and drive the page in Chromium: every way of signing in, sessions ending, the WebSocket dropping and coming back, shells, logs and Helm. tests/web/fleet*.spec.ts do the same for a fleet: its page, where its clusters come from, and agents relaying to clusters the server can’t reach.
  • Plugin checks (npm run plugins:check) check every kind, path, template, link, related list and action in Lumovi’s plugins against the CRDs of their tools, which Lumovi-plugins keeps beside each plugin. A misremembered field fails here, rather than showing nothing in the app.
  • Integration tests check the same app against a real three-node kind cluster with metrics-server and kube-prometheus-stack. They change things for real and check the result with kubectl, and they install the image with the Helm chart and sign in to it, behind a proxy and with a token. They need Docker, kind, kubectl and Helm:
    npm run test:kind creates the cluster and runs the tests in one go. The cluster gets its own kubeconfig in .kind/. Your ~/.kube/config isn’t read or changed.

Contributing

Bug reports, ideas and pull requests are welcome. The contributing guide has the details; in short:
1

Agree on the approach

For anything bigger than a small fix, open an issue first. Lumovi is for looking after workloads, clusters and Helm releases; managing kubeconfig files is out of scope.
2

Make a focused change

Branch from main, and match the style of the code around it: TypeScript in strict mode, Prettier and ESLint, and the design tokens for anything visual.
3

Test it like a user

Add or update end-to-end tests in tests/e2e/ (and tests/web/ for what’s different when served). Tests drive the real app through its interface. A new cluster state goes in the demo fixture, tests/mock-cluster/fixtures/, when it’s realistic.
4

Check it

Run npm run verify. Screenshots help for interface changes: on a Mac, npm run screenshots -- overview pods takes those two, light and dark.
5

Open a pull request

Describe what changed and why.

Adding a tool

Lumovi shows what popular operators run through plugins, written as YAML in the plugin format. A plugin gives a tool its entry in the sidebar and lists its kinds, and its views say how each kind is shown. Adding a tool needs no code, and is a welcome first contribution. The plugins Lumovi comes with live in their own repository, Lumovi-plugins: a tool is added there, checked by Lumovi’s own checker against its pinned CRDs, and released as one signed bundle. See Contributing a plugin. Lumovi is built with the release plugins.lock.json names, and checks it again as it’s built. To try a plugin while you write it, put its file in ~/.lumovi/plugins while running npm run dev against a cluster with the tool installed. Plugins are read again when you refresh (⌘R; CtrlR on Windows and Linux). To ask for a tool instead, open a Support a tool issue. Found a security problem? Please report it privately: see Reporting a vulnerability.