Native desktop shell for the Nimbus operator console.
nimbus-desktop is a signed, notarized, auto-updating Electron
application that wraps the operator console UI served by a local
nimbus instance. It is separate from nimbus/nimbus by design
so the desktop release cadence, packaging matrix, and signing
credentials stay isolated from the core server.
The desktop shell connects to a nimbus server — it does not ship
one. Install the CLI first:
# macOS / Linux (Homebrew)
brew install nimbus/tap/nimbusOther platforms and direct downloads:
nimbus/nimbus install reference.
macOS — Homebrew Cask (recommended)
brew install --cask nimbus/tap/nimbus-desktopThe cask installs nimbus-desktop.app into /Applications from a
signed, notarized DMG, and auto_updates true defers upgrade
management to the in-app updater (no brew upgrade needed).
Direct download (macOS / Linux)
| Platform | Download | Notes |
|---|---|---|
| macOS | nimbus-desktop-<version>-universal.dmg |
Universal binary (arm64 + x64), notarized. |
| Linux | nimbus-desktop-<version>-x86_64.AppImage |
Self-contained. chmod +x and run. |
nimbus-desktop_<version>_amd64.deb |
Debian / Ubuntu: sudo apt install ./*.deb |
|
nimbus-desktop-<version>.x86_64.rpm |
Fedora / RHEL: sudo dnf install ./*.rpm |
|
| Windows | nimbus-desktop-Setup-<version>-x64.exe |
Unsigned — SmartScreen warning on first launch (decision 002). |
Latest releases live at github.com/nimbus/desktop/releases.
# macOS
open -a nimbus-desktop
# Linux
nimbus-desktop
# Windows
"%LOCALAPPDATA%\Programs\nimbus-desktop\nimbus-desktop.exe"On first launch the shell discovers a local nimbus instance via
server.json (see File locations). If none is
running, the shell spawns one in the background and waits for it to
become ready (~1-2 s). The window opens to the operator console at
/ui/.
Updates ship automatically via
electron-updater from
GitHub Releases. The shell polls on launch and at idle, downloads
in the background, and installs on the next operator-initiated quit
(never a forced restart). Signature verification is enforced
end-to-end; an update with a broken signature is rejected.
The desktop shell and the nimbus CLI it spawns update on independent
cadences. For the full picture — how the CLI updates, what the staleness
indicators in the SPA mean, what the in-app Update button does, and
how to disable update checks on air-gapped hosts — see
docs/operating/updates.md in nimbus/nimbus.
The shell could not find a running nimbus. Confirm:
nimbus --version # is it installed?
nimbus start # start it manually
ls ~/.config/nimbus/server.json # was server.json written?On macOS the discovery path is
~/Library/Application Support/nimbus/server.json. On Windows it is
%APPDATA%\nimbus\server.json.
Re-launch the app. If it persists, check
~/Library/Caches/nimbus-desktop-updater/ (macOS),
~/.cache/nimbus-desktop-updater/ (Linux), or
%LOCALAPPDATA%\nimbus-desktop-updater\ (Windows) — clearing this
directory forces a fresh download. The shell will fall through to a
manual-download notification if the auto-update path keeps failing.
Open the developer Help → "Toggle DevTools" entry (production builds
include DevTools but log only). If the console shows
net::ERR_CONNECTION_REFUSED, nimbus is not running on the
discovered address. Restart with nimbus start.
| Resource | macOS | Linux | Windows |
|---|---|---|---|
| App settings | ~/Library/Application Support/nimbus-desktop/ |
~/.config/nimbus-desktop/ |
%APPDATA%\nimbus-desktop\ |
| Logs | ~/Library/Logs/nimbus-desktop/ |
~/.config/nimbus-desktop/logs/ |
%APPDATA%\nimbus-desktop\logs\ |
| Updater cache | ~/Library/Caches/nimbus-desktop-updater/ |
~/.cache/nimbus-desktop-updater/ |
%LOCALAPPDATA%\nimbus-desktop-updater\ |
server.json discovery |
~/Library/Application Support/nimbus/server.json (read-only — owned by nimbus) |
~/.config/nimbus/server.json (read-only) |
%APPDATA%\nimbus\server.json (read-only) |
| macOS | Drag nimbus-desktop.app to Trash. Remove ~/Library/Application Support/nimbus-desktop/, ~/Library/Logs/nimbus-desktop/, ~/Library/Caches/nimbus-desktop-updater/. |
|---|---|
| Linux | sudo apt remove nimbus-desktop (deb) or sudo dnf remove nimbus-desktop (rpm). AppImage: delete the file. Remove ~/.config/nimbus-desktop/ and ~/.cache/nimbus-desktop-updater/. |
| Windows | Settings → Apps → nimbus-desktop → Uninstall. Remove %APPDATA%\nimbus-desktop\ and %LOCALAPPDATA%\nimbus-desktop-updater\. |
Removing nimbus-desktop does not remove nimbus itself. Uninstall
nimbus via its own install script
if you want to clean up the server too.
See docs/security-posture.md for the
reviewable summary of how the shell isolates the renderer, locks
down Electron Fuses, and signs releases. No telemetry is sent by
default. The renderer is sandboxed, context-isolated, and has
nodeIntegration: false.
This repo is a Phase 2 deliverable of the desktop initiative.
The roadmap lives at
docs/plans/desktop-shell-plan.md
in nimbus/nimbus.
Stack:
- Electron 42, electron-builder 26, electron-updater 6
- TypeScript 6 strict, Biome 2.4
- Vitest (unit), Playwright (packaged-shell E2E)
npm ci
npm run dev # build main + launch
npm run test # vitest unit tests
npm run package # local unsigned package (verifies wiring)
npm run package:mac # signed if Developer ID is in keychainReleases are cut by tagging v* on main; the CI workflow in
.github/workflows/release.yml
produces signed installers and publishes them. See
docs/release-runbook.md for the
release process and credential rotation.
External decisions for signing, notarization, and update hosting
live in docs/decisions/:
Same as nimbus/nimbus. See the parent repo for license details.