Desktop-App

Die Desktop-App ist ein lokales NodePilot-Paket für Windows 11 x64. Ein Installer richtet API, Produktoberfläche, Electron-Shell und PostgreSQL ein. Externe Laufzeiten, eine externe Datenbank und Internetzugriff sind während der Installation nicht erforderlich.

Einsatzbereich

Geeignet für:

• produktive Automatisierung auf einem einzelnen Windows-System
• lokale Zeitplan-, Datei-, Datenbank- und Eventlog-Trigger
• ausgehende WinRM-, REST-, SQL-, SMTP- und Alerting-Verbindungen
• Offline-Installation

Nicht geeignet für:

• Zugriff von anderen Systemen
• eingehende Webhooks
• externe REST- oder Trigger-API
• LDAP, Windows SSO, OIDC oder SCIM
• Hochverfügbarkeit

Laufzeitarchitektur

Electron-Shell
      |
      | HTTPS auf localhost, Zertifikat gepinnt
      v
Windows-Dienst "NodePilot"       LocalSystem
      |
      v
Windows-Dienst "NodePilotDb"     NetworkService
      |
      v
PostgreSQL 16 auf 127.0.0.1

Die Dienste starten beim Systemstart. Das Schließen des Electron-Fensters beendet keine Workflows oder Trigger.

Stoppt oder hängt NodePilotDb im laufenden Betrieb, bleibt die API erreichbar und die Oberfläche zeigt einen Datenbank-Ausfall. Datenbankzugriffe antworten schnell mit 503, Workflows warten an dauerhaften Schrittgrenzen und der Betrieb wird nach erfolgreicher PostgreSQL-Prüfung automatisch fortgesetzt. Diagnose: /healthz/ready und /healthz/database. Details und Timeout-Einstellungen: Datenbank-Provider.

Fenster- und Infobereichssymbol übernehmen die Farbe des in der Oberfläche gewählten Skins. Das Symbol der Programmdatei, des Installers und des Startmenüeintrags bleibt beim blauen Standard, da Windows diese Symbole aus der Datei selbst auflöst.

Installierte Pfade

Sicherheitsmodell

Deployment:Mode=Desktop setzt folgende Regeln:

• Kestrel bindet ausschließlich an Loopback.
• Es wird keine eingehende Firewallregel angelegt.
• PostgreSQL bindet ausschließlich an 127.0.0.1.
• Ein self-signed Zertifikat schützt die lokale HTTPS-Verbindung.
• Electron prüft den SHA-256-Fingerprint des Zertifikats.
• Das Zertifikat wird nicht als globale Root-CA installiert.
• Electron verwendet contextIsolation, sandbox und webSecurity.
• Node-Integration, externe Navigation und Berechtigungsanfragen sind deaktiviert. Das Produktfenster hat keine Preload-Bridge; nur das Ersteinrichtungsfenster hat eine schmale Bridge, die Benutzername und Passwort übergibt. Das einzige zugelassene Pop-up ist das Dokumentationsfenster unter /docs.
• Downloads sind nur von der eigenen Herkunft der Anwendung zugelassen; das Ziel wählt der native Speichern-unter-Dialog.

Ein normaler Browser kann für die lokale URL eine Zertifikatswarnung anzeigen. Der unterstützte Zugriff erfolgt über die Electron-Shell.

Rechte lokaler und entfernter Ausführung

Die API läuft als LocalSystem. Daraus folgen zwei unterschiedliche Fälle:

Credential-lose Kerberos-Delegation ist im Desktop-Modus nicht vorgesehen.

Installer-Verfügbarkeit

NodePilot-Desktop-Setup-<version>.exe hängt als Asset am aktuellen Release; die zugehörigen Prüfsummen stehen in NodePilot-<version>.SHA256SUMS.txt.

Auch der signierte Installer löst beim ersten Start SmartScreen aus, sobald er heruntergeladen wurde — das Zertifikat ist selbstsigniert und trägt keine Reputation. Erklärung und Vorgehen: Beim ersten Start: das blaue SmartScreen-Fenster.

Der Installer bleibt daneben ein Build-Ziel des Repositorys — der Abschnitt unten beschreibt, wie er selbst erzeugt wird. Eine selbst gebaute .exe ist zusätzlich unsigniert, bis sie mit einem eigenen Authenticode-Zertifikat signiert wird.

Installer bauen

Voraussetzungen auf dem Build-System

• .NET 10 SDK
• Node.js und npm
• Inno Setup 6 mit ISCC.exe
• PostgreSQL-16-Binärverzeichnis pgsql
• Authenticode-Zertifikat für die Verteilung

Build aus deploy\desktop:

Set-Location deploy\desktop
.\Build-DesktopInstaller.ps1 `
  -PgBinariesPath "C:\Packages\pgsql" `
  -Version 1.0.0

Ergebnis:

out\NodePilot-Desktop-Setup-1.0.0.exe

Der Build:

1. veröffentlicht die API self-contained für win-x64,
2. veröffentlicht die Operator-Clients (np, nodepilot-mcp) self-contained nach tools\np und tools\mcp,
3. baut die React-Oberfläche,
4. kopiert erforderliche PowerShell-Module,
5. paketiert die Electron-Shell,
6. übernimmt den benötigten PostgreSQL-Teil,
7. erzeugt den Inno-Setup-Installer.

Der erzeugte Installer muss vor der Verteilung mit Authenticode signiert werden.

Installation

1. Signierten Installer auf das Windows-11-Zielsystem übertragen.
2. Installer mit UAC-Bestätigung starten.
3. Provisionierung vollständig abschließen lassen.
4. Electron-Shell starten.
5. Lokalen Admin-Account im Setup-Dialog anlegen.

NodePilot hat kein Standardkonto und kein Standardpasswort. Name und Passwort aus dem Setup-Dialog (mindestens 8 Zeichen) sind ab dann die Anmeldung des Administrators.

Liegen noch Daten einer früheren, deinstallierten NodePilot-Installation auf dem Rechner, fragt das Setup, was damit geschehen soll:

Unbeaufsichtigt behält das Setup die Daten; /DISCARDDATA=1 löscht sie.

Der Installer:

• installiert Dateien,
• initialisiert PostgreSQL,
• registriert NodePilotDb und NodePilot,
• erzeugt das Loopback-Zertifikat,
• schreibt die Produktionskonfiguration,
• setzt ACLs,
• erstellt desktop.json,
• übergibt den einmaligen Setup-Token geschützt an die Electron-Shell.

Der Setup-Token geht in das Profil des Benutzers, der den Installer gestartet hat — also des Benutzers, unter dem die Shell anschließend läuft. Das ist nicht zwingend das Konto, unter dem der Installer läuft: Der Installer läuft eleviert, und gibt ein Standardbenutzer am UAC-Dialog die Anmeldedaten eines anderen Administratorkontos ein, sind das zwei verschiedene Profile. Auch der Konsolenbenutzer taugt nicht als Ersatz, denn bei Remotedesktop oder einem Benutzerwechsel ist das jemand anderes. Der Installer ermittelt deshalb das Konto, das ihn gestartet hat, und übergibt den Token genau diesem Konto. Lässt sich das Konto nicht ermitteln, bricht die Provisionierung mit einer Meldung ab, statt den Token einem anderen Profil zu geben. Startet eine Softwareverteilung den Installer als SYSTEM, läuft unter diesem Konto keine Shell; der Token geht dann an den an der Konsole angemeldeten Benutzer oder bleibt bei SYSTEM, wenn niemand angemeldet ist.

Scheitert die Provisionierung, meldet der Installer das mit einem Verweis auf sein Log unter %TEMP%\nodepilot-provision.log und startet die Shell nicht — statt eine erfolgreiche Installation zu melden, die anschließend nicht startet. Ursachen und Abhilfen stehen im Desktop-Troubleshooting, eine Übersicht aller Logdateien unter Logs & Diagnose.

Dokumentation auf dem Gerät

Das Paket bringt diese Dokumentation mit; die API liefert sie unter /docs aus. Der Dokumentations-Knopf unten links in der Seitenleiste, neben Skin- und Sprachwahl, öffnet sie in einem eigenen Fenster — ohne Anmeldung und ohne Internetzugang, passend zur installierten Version. Links aus der Dokumentation nach außen (GitHub, Releases) öffnet die Shell im Systembrowser; sie stellt selbst keine fremden Inhalte dar.

Sie ist verfügbar, solange der Dienst NodePilot läuft — auch dann noch, wenn die Datenbank gerade nicht erreichbar ist. Startet der Dienst gar nicht, hilft nur das Provisionierungslog.

Installation prüfen

Get-Service NodePilotDb, NodePilot
Get-Content "$env:ProgramData\NodePilot\desktop.json"

Erwartete Ergebnisse:

Der Origin aus desktop.json kann lokal geprüft werden:

$desktop = Get-Content "$env:ProgramData\NodePilot\desktop.json" | ConvertFrom-Json
Invoke-WebRequest "$($desktop.origin)/healthz/ready" -SkipCertificateCheck

-SkipCertificateCheck steht in PowerShell 7 zur Verfügung und ist hier nur für die lokale Diagnose des self-signed, durch Electron gepinnten Zertifikats vorgesehen.

Update

Ein neuer signierter Installer kann über die bestehende Installation ausgeführt werden, ebenso dieselbe Version erneut. Die Shell darf dabei geöffnet bleiben; das Setup beendet sie.

Update-Ablauf:

1. ACL-geschütztes pg_dump unter C:\ProgramData\NodePilot\backups erstellen (die neuesten drei bleiben).
2. Shell und die Clients np/nodepilot-mcp beenden, beide Dienste stoppen und warten, bis ihre Prozesse beendet sind — bevor eine Datei ersetzt wird.
3. Binaries ersetzen.
4. Vorhandenes PostgreSQL-Datenverzeichnis weiterverwenden: Konten, Workflows und Einstellungen bleiben erhalten.
5. Dienste neu provisionieren.
6. Health-Endpunkt prüfen. Bricht Windows einen langsamen ersten Start des API-Dienstes ab, startet das Setup ihn erneut.

Lässt sich die laufende Installation nicht stoppen, bricht das Setup ab, bevor es eine Programmdatei ändert, und nennt sein Log, %TEMP%\nodepilot-setup-prepare.log.

Update-Desktop.ps1 bietet zusätzlich ein gestuftes Update mit Rollback für Binaries, Konfiguration und Datenbank.

Sicherheitsupdates der Laufzeit kommen mit dem Desktop-Paket. API, np und nodepilot-mcp bringen ihre eigene .NET-Laufzeit mit. Ein systemweites .NET- oder Windows-Update ersetzt sie nicht; eine bestehende Installation erhält eine gepatchte Laufzeit nur, wenn ein neues Desktop-Paket darüber installiert wird. Desktop-Pakete ab 1.5.4 enthalten .NET 10.0.14, das die Kestrel-Sicherheitshinweise CVE-2026-88092 und CVE-2026-70188 für 10.0.12 und älter schließt. Ältere Desktop-Installationen mit einem solchen Paket aktualisieren.

PostgreSQL-Major-Upgrades und Electron-Auto-Update sind nicht Bestandteil der aktuellen Desktop-Version.

Deinstallation

NodePilot über Apps & Features deinstallieren. Die Deinstallation entfernt immer:

• die Shell und die Clients np/nodepilot-mcp, falls sie laufen,
• beide Windows-Dienste,
• das Loopback-Zertifikat samt privatem Schlüssel,
• die Dateien unter C:\Program Files\NodePilot.

Danach fragt sie nach den Daten:

Unbeaufsichtigt bleiben die Daten erhalten:

& 'C:\Program Files\NodePilot\unins000.exe' /VERYSILENT /SUPPRESSMSGBOXES               # Daten behalten
& 'C:\Program Files\NodePilot\unins000.exe' /VERYSILENT /SUPPRESSMSGBOXES /PURGEDATA=1  # alles löschen

„Alles löschen" ist nicht rückgängig zu machen. Werden die Daten eventuell noch gebraucht, vorher ein Backup erstellen.

Konnte etwas nicht entfernt werden, meldet die Deinstallation das und nennt ihr Log, %TEMP%\nodepilot-uninstall.log.

Backup und Systemwechsel

Für den Schutz der Konfiguration:

1. System-Configuration-Backup in NodePilot erstellen.
2. Backup-Datei und Passphrase getrennt sichern.
3. Für vollständige Historie zusätzlich PostgreSQL sichern.

Ein Kopieren von pgdata auf einen anderen Rechner ist kein unterstützter Migrationsweg. Credentials sind bei DPAPI-Nutzung an die Maschine gebunden. Der unterstützte Wechsel verwendet das System-Configuration-Backup, damit Secrets im Zielsystem neu verschlüsselt werden.

Bekannte Grenzen

• Installer muss im Release-Prozess signiert werden.
• PostgreSQL-Major-Upgrades sind nicht automatisiert.
• Electron besitzt keinen Auto-Updater.
• Installation und Rollback benötigen einen Test auf einer sauberen Windows-11-VM.
• Desktop-Modus ist absichtlich auf einen lokalen Einzelplatz begrenzt.

Die vollständigen Build- und Validierungsdetails stehen in deploy\desktop\README.md.