Build from source and contribute

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

Build the app

You need Node.js 24 or later (the repository’s .nvmrc asks for 26) and npm. 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).

Get the code

git clone https://github.com/Lumovi/Lumovi
cd Lumovi
nvm use   # if you use nvm: picks the Node.js version in .nvmrc
npm ci

Build the installers

npm run dist

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.

A copy you build yourself isn’t signed or notarized. For everyday use, the official releases are signed on macOS 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

npm run dev:mock    # the app against built-in demo clusters, no Kubernetes needed
npm run dev         # the app against your own kubeconfig
npm run dev:server  # Lumovi served, as in a cluster, against the demo clusters

dev and dev:mock reload as you change the code. 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.

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

Command	What it does
`npm run dev` / `dev:mock`	Run with hot reload (your clusters / the demo clusters)
`npm run dev:server`	Build and serve Lumovi against the demo clusters
`npm run build`	Build the app and the server into `out/`
`npm run start`	Run the built app
`npm run serve`	Run the built server (`out/server`)
`npm run mock-cluster`	Start the demo clusters alone, and print a kubeconfig for them
`npm run verify`	Format, lint, types, views, and e2e tests with coverage, as CI checks them
`npm run test:e2e`	Build with coverage instrumentation, and run the e2e tests
`npm run test:linux`	The same, on Linux in Docker, as CI runs it
`npm run coverage`	The e2e tests, plus a coverage report in `coverage/`
`npm run coverage:check`	Fail unless every file, line, branch and function is covered
`npm run lint` / `typecheck` / `format`	Static checks
`npm run views:check`	Check Lumovi’s views and add-ons against the CRDs of their tools
`npm run crds`	Fetch those CRDs again, at the versions `tests/views/crds/sources.json` pins
`npm run test:kind`	Create a local kind cluster, and run the integration tests against it
`npm run screenshots`	Take the screenshots in `docs/screenshots` again
`npm run package`	Build an unpacked app for this platform in `release/`
`npm run dist`	Build installers for this platform

How it’s built

src

main

backend

server

preload

renderer

shared

charts

tests

e2e

web

views

mock-cluster

mock-oidc

integration

docs

build

scripts

Folder	What’s in it
`src/main`	The Electron main process: the window, menus, updates and IPC
`src/backend`	Kubeconfigs, API requests, Helm, shells and logs, for the desktop app and the server alike
`src/server`	Lumovi served from a cluster: sign-in, the page, a WebSocket for each page
`src/preload`	The narrow, typed bridge the page gets as `window.lumovi`
`src/renderer`	The React interface (Tailwind CSS, TanStack Query, Radix, cmdk), and Lumovi’s views and add-ons, in `src/renderer/src/views`
`src/shared`	Types and the resource registry every side uses
`charts`	The Helm chart that runs the server, whose image the `Dockerfile` builds
`tests`	The e2e and web tests, the views’ checks against their tools’ CRDs, the mock API server and OpenID Connect provider, and integration tests
`docs`	The development guide, and the screenshots these docs show. The rest of the documentation is here.
`build`	The app’s icons and the installers’ artwork, from Lumovi’s design repository
`scripts`	The demo clusters for `dev:mock` and `dev:server`, Linux test runs, coverage tooling, the views’ CRDs, screenshots, and the Helm chart’s version

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 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 never reach the page. It runs sandboxed, with context isolation, no Node.js access and a strict Content Security Policy. Every IPC call is checked for its sender and validated in the main process, the only place that talks to clusters. See Privacy and security.
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 100% end-to-end coverage of statements, branches, functions and lines, enforced in CI.

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.
View checks (npm run views:check) check every kind, path, template, link, related list and action in Lumovi’s views and add-ons against the CRDs of their tools, pinned in tests/views/crds/sources.json. 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 kind:up # create the cluster (a few minutes) npm run test:integration # build, then run the integration tests npm run kind:down # delete the cluster
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:

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.

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.

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.

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.

Open a pull request

Describe what changed and why.

Adding a tool

Lumovi shows what popular operators run through views and add-ons, written as YAML in src/renderer/src/views/<tool>.yaml, in the view format. An add-on gives a tool its entry in the sidebar and lists its kinds; views say how each kind is shown. Adding a tool needs no code, and is a welcome first contribution.

Pin the tool's CRDs

Add its release to tests/views/crds/sources.json, under the add-on’s name, with the URLs of its CRD manifests, and run npm run crds -- <name>. That keeps what the check needs in tests/views/crds/<name>.json.

Write the add-on and its views

In src/renderer/src/views/<name>.yaml, write the AddOn, then a View for each kind worth more than the generic columns. Status rules help most: say what healthy, in progress, failing and paused look like for this tool.

Check them

Run npm run views:check. Labels and annotations aren’t in schemas, so check those against the tool’s documentation, or a real cluster.

Look at it

Put the file in ~/.lumovi/views while running npm run dev against a cluster with the tool installed. Views 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.

Reference

Help

Project

Build from source and contribute

Build the app

Run it while you work on it

Commands

How it’s built

Tests

Contributing

Adding a tool

​Build the app

​Run it while you work on it

​Commands

​How it’s built

​Tests

​Contributing

​Adding a tool

Build the app

Run it while you work on it

Commands

How it’s built

Tests

Contributing

Adding a tool