desktopkit Web UI — Hilfe

1. Übersicht

desktopkit ist ein Toolkit zur Desktop-Automatisierung für Call-Center-Umgebungen. Es besteht aus eigenständigen Binaries, die Screenshots aufnehmen, Maus und Tastatur steuern, die Zwischenablage verwalten und Fenster kontrollieren können — alles auf Linux-Desktops (Ubuntu mit X11/Xvfb).

Die Web UI ist die grafische Oberfläche des desktopkit-server. Sie erlaubt es, einen entfernten Linux-Desktop live zu sehen und interaktiv zu steuern — direkt aus dem Browser, ohne VNC oder RDP. Die UI bietet:

• Live-Screenshot mit konfigurierbarem Auto-Refresh
• Maus- und Tastatursteuerung per Klick und Kontextmenü
• Zwischenablage lesen und schreiben
• Anwendungen starten, prüfen und schließen
• Fensterliste mit Aktivieren/Schließen
• Annotations (Crosshair, Bounding Boxes)
• Vollständige Aktions-History

2. Login & Authentifizierung

Beim Öffnen der Web UI erscheint ein Login-Screen. Der Benutzername des Linux-Users, unter dem der Server läuft, wird automatisch angezeigt.

Passwort-Login

Geben Sie das Passwort ein und klicken Sie Login oder drücken Sie Enter. Das Passwort entspricht dem in /opt/desktopkit/secret hinterlegten Token. Bei Erfolg wird ein Bearer-Token in der sessionStorage gespeichert.

Auto-Login per URL-Parameter

Für automatisierte Zugriffe kann das Passwort direkt in der URL übergeben werden:

https://host:port/?password=mein-token

Der Login wird automatisch ausgeführt. Das ist nützlich für KI-Agenten oder Bookmarks mit gespeichertem Zugang.

Session-Handling

• Das Token wird in der sessionStorage des Browsers gespeichert (gilt nur für den aktuellen Tab).
• Bei einem HTTP-401-Fehler (Token ungültig/abgelaufen) wird automatisch zur Login-Seite zurückgeleitet.
• Beim Laden der Seite wird geprüft, ob ein vorhandenes Token noch gültig ist (/auth/token-info).
• Der Logout-Button oben rechts beendet die Session serverseitig und löscht das lokale Token.

3. Screenshot & Zoom

Der Screenshot-Bereich ist das Herzstück der UI. Er zeigt den aktuellen Zustand des Remote-Desktops als Live-Bild.

Capture-Button

Klicken Sie Capture in der Toolbar, um sofort einen neuen Screenshot aufzunehmen. Gleichzeitig werden die Cursor-Position und das aktive Fenster aktualisiert.

Auto-Refresh

Aktivieren Sie die Checkbox Auto neben dem Capture-Button, um automatisch in regelmäßigen Abständen neue Screenshots zu laden. Das Intervall ist einstellbar:

Bei jedem Auto-Refresh werden auch die Host-Cursor-Position und der aktive Fenstertitel aktualisiert.

Zoom

Der Zoom-Slider reicht von 25% bis 400%. Die Skalierung erfolgt serverseitig über den Parameter scale_factor — der Server liefert das Bild direkt in der gewünschten Auflösung. Das spart Bandbreite bei niedrigem Zoom und ermöglicht scharfe Vergrößerung bei hohem Zoom.

Der Zoom-Wert wird in der Toolbar als Prozent angezeigt (z.B. 100%). Beim Ändern des Sliders wird der Auto-Refresh kurz pausiert, ein neuer Screenshot mit dem angepassten Scale-Factor geladen, und der Auto-Refresh danach fortgesetzt.

Bildgröße

Rechts neben dem Zoom wird die aktuelle Dateigröße des Screenshots angezeigt (z.B. 245 KB oder 1.2 MB). Das hilft, die Bandbreite im Blick zu behalten.

Screen-Auswahl

Falls der Remote-Desktop mehrere Bildschirme hat, können Sie über das Dropdown Screen den gewünschten Monitor auswählen. Die verfügbaren Screens werden beim App-Start vom Server abgefragt (/screens).

Host-Cursor

In der Toolbar wird die aktuelle Cursor-Position des Remote-Hosts angezeigt (z.B. Host: 512, 384). Diese wird bei jedem Capture und Auto-Refresh über den Endpoint /screenshot/cursor-position abgefragt.

Aktives Fenster

Rechts in der Toolbar wird der Titel des aktuell aktiven Fensters angezeigt. Bei langen Titeln wird der Text abgeschnitten (Ellipsis), der vollständige Titel ist per Tooltip sichtbar.

4. Sidebar & Flyout Panel

Am linken Rand befindet sich die Sidebar mit Icon-Buttons für jedes Werkzeug. Daneben öffnet sich bei Bedarf das Flyout Panel mit den Steuerelementen.

Hover-Verhalten

Im Normalzustand zeigt die Sidebar nur Icons (48px breit). Wenn Sie mit der Maus darüber fahren, erweitert sich die Sidebar auf 150px und zeigt die Beschriftungen der Buttons an. Gleichzeitig öffnet sich das Flyout Panel mit dem aktiven Werkzeug.

Pin-Button

Klicken Sie den Pin-Button (Stecknadel-Icon) ganz oben in der Sidebar, um die Sidebar und das Flyout Panel dauerhaft geöffnet zu halten. Im gepinnten Zustand wird der Pin-Button farblich hervorgehoben. Ein erneuter Klick löst die Fixierung.

Tab-Wechsel

Klicken Sie auf einen der Sidebar-Buttons, um zwischen den Werkzeugen zu wechseln:

Der aktuell aktive Tab wird rot hervorgehoben.

Persistenz

Folgende Einstellungen werden in der localStorage des Browsers gespeichert und beim nächsten Laden wiederhergestellt:

• Pin-Status (Sidebar fixiert oder nicht)
• Aktiver Tab (welches Werkzeug ausgewählt ist)
• Zoom-Stufe
• Auto-Refresh an/aus und Intervall
• History-Panel offen/geschlossen

5. Maussteuerung

Das Mouse-Panel bietet volle Kontrolle über die Maus des Remote-Desktops.

Position setzen

Die Felder X und Y zeigen die aktuelle Zielposition. Sie können die Werte manuell eingeben oder durch Klick/Rechtsklick auf den Screenshot setzen. Der Button Move bewegt die Maus an die angegebene Position.

Klick-Aktionen

Wählen Sie im Dropdown die Maustaste (Left, Right, Middle), dann:

• Click — Einfacher Klick an der aktuellen X/Y-Position
• Dbl-Click — Doppelklick an der aktuellen X/Y-Position

Nach jedem Klick wird automatisch nach 1 Sekunde ein neuer Screenshot aufgenommen, um das Ergebnis zu sehen.

Scrollen

Geben Sie die Scroll-Richtung als Delta-Werte ein:

• dX — Horizontales Scrollen (positiv = rechts, negativ = links)
• dY — Vertikales Scrollen (negativ = nach oben, positiv = nach unten; Standardwert: -3)

Der Scroll-Befehl wird an der aktuellen Mausposition (X/Y) ausgeführt.

Drag & Drop

Geben Sie die Start-Koordinaten (Von: X, Y) und Ziel-Koordinaten (Nach: X, Y) ein und klicken Sie Drag. Die Maus wird mit gedrückter linker Taste von Start zu Ziel gezogen.

Rechtsklick-Kontextmenü auf dem Screenshot

Ein Rechtsklick auf den Screenshot öffnet ein Kontextmenü mit Schnellaktionen. Die Koordinaten unter dem Cursor werden automatisch in die X/Y-Felder übernommen.

Koordinaten-Tooltip

Wenn Sie die Maus über den Screenshot bewegen, erscheint ein Tooltip mit den aktuellen Koordinaten (in Original-Auflösung, unabhängig vom Zoom). Die Koordinaten werden live aktualisiert und entsprechen den tatsächlichen Pixelpositionen auf dem Remote-Desktop.

6. Tastatursteuerung

Das Keyboard-Panel sendet Tastatureingaben an den Remote-Desktop.

Text eingeben (Type)

Geben Sie beliebigen Text in das Eingabefeld ein und klicken Sie Type oder drücken Sie Enter. Der Text wird zeichenweise über xdotool type eingegeben, als würde jemand auf der Tastatur tippen.

Hotkey-Kombination

Aktivieren Sie die gewünschten Modifier-Tasten per Checkbox:

• Ctrl, Alt, Shift, Super (Windows-Taste)

Geben Sie dann die Taste im Feld ein (z.B. a, F5, v) und klicken Sie Send oder drücken Sie Enter.

Beispiele:

• Ctrl + c — Kopieren
• Ctrl + v — Einfügen
• Alt + F4 — Fenster schließen
• Ctrl + Shift + t — Tab wiederherstellen (Browser)
• Super — Nur Super-Taste (Aktivitäten/Start-Menü)

Schnelltasten

Häufig benötigte Tasten sind als Buttons direkt verfügbar:

7. Clipboard

Das Clipboard-Panel ermöglicht den Zugriff auf die Zwischenablage des Remote-Desktops.

Zwischenablage lesen

Klicken Sie Read Clipboard, um den aktuellen Inhalt der Remote-Zwischenablage abzurufen. Der Text wird im darunterliegenden (schreibgeschützten) Textfeld angezeigt.

Zwischenablage schreiben

Geben Sie den gewünschten Text in das untere Textfeld ein und klicken Sie Write. Der Text wird in die Zwischenablage des Remote-Desktops geschrieben und kann dort mit Ctrl+V eingefügt werden.

8. Anwendungen

Das Apps-Panel dient zum Starten, Prüfen und Schließen von Anwendungen auf dem Remote-Desktop.

Schnellstart

Vorkonfigurierte Buttons zum schnellen Starten häufig benötigter Anwendungen:

• Chrome — Startet google-chrome --no-sandbox
• Calc — Startet libreoffice --calc

Nach dem Start wird nach 2 Sekunden automatisch ein neuer Screenshot aufgenommen.

Anwendung starten (Pfad + Argumente)

Für beliebige Programme: Geben Sie den Pfad oder Befehlsnamen im Feld Pfad ein (z.B. firefox, /usr/bin/gedit). Optionale Argumente können im Pfad-Feld (durch Leerzeichen getrennt) oder im separaten Feld Args (durch Komma getrennt) angegeben werden. Klicken Sie dann Open.

Status prüfen

Geben Sie einen Prozessnamen ein (z.B. firefox) und klicken Sie Check. Das Ergebnis zeigt Running oder Not running an.

Fenster schließen

Geben Sie die Window-ID (WID) ein und klicken Sie Close. Die WID können Sie aus der Fensterliste (Windows-Panel) entnehmen.

9. Fensterverwaltung

Das Windows-Panel zeigt alle offenen Fenster des Remote-Desktops und ermöglicht deren Verwaltung.

Fenster auflisten

Klicken Sie Refresh, um die aktuelle Fensterliste vom Server abzurufen. Jeder Eintrag zeigt:

• Window-ID (links, monospace) — Eindeutige Kennung
• Fenstertitel (Mitte) — Anzeigename des Fensters
• Prozessname (rechts, grau) — Name des zugehörigen Prozesses

Aktives Fenster

Das aktuell fokussierte Fenster wird visuell hervorgehoben:

• Grüner Rand (statt grauer Rand)
• Grüner Hintergrund (leicht transparent)
• ACTIVE-Badge am rechten Rand

Fenster aktivieren (Linksklick)

Ein einfacher Klick auf einen Fenstereintrag bringt dieses Fenster in den Vordergrund und gibt ihm den Fokus. Nach 500ms werden die Fensterliste und der Screenshot aktualisiert.

Kontextmenü (Rechtsklick)

Ein Rechtsklick auf einen Fenstereintrag öffnet ein Kontextmenü mit zwei Optionen:

• Aktivieren — Fenster in den Vordergrund bringen
• Schließen — Fenster schließen (sendet eine Close-Anfrage an die Anwendung)

Dialog erkennen

Der Button Check Dialog prüft, ob ein modaler Dialog (z.B. ein Bestätigungsfenster, eine Fehlermeldung) auf dem Desktop geöffnet ist. Das Ergebnis wird als Hinweis unterhalb der Fensterliste angezeigt, einschließlich des Dialog-Titels falls vorhanden.

10. History / Verlauf

Am unteren Bildschirmrand befindet sich die History-Leiste, die alle ausgeführten Aktionen protokolliert.

Einzeiler (zusammengeklappt)

Im zusammengeklappten Zustand zeigt die History-Leiste nur eine Zeile mit dem zuletzt ausgeführten Befehl (rot hervorgehoben). Ein Klick auf die Leiste klappt sie auf.

Toggle

Die History kann über zwei Wege ein- und ausgeklappt werden:

• Der History-Button (🕐) in der Sidebar
• Klick auf die History-Toolbar im zusammengeklappten Zustand

Einträge

Jeder Eintrag zeigt:

• Uhrzeit (grau, links)
• Aktion (rot, entweder der Shell-Befehl oder der API-Request)

Ein Klick auf einen Eintrag klappt ihn auf und zeigt Details:

• Request — Die gesendete API-Anfrage (Methode + Pfad + Body)
• Command — Der intern ausgeführte Shell-Befehl (falls vorhanden)
• Response — Die Server-Antwort als JSON (ohne Bilddaten)

Fehlerhafte Aktionen werden mit roter Aktion dargestellt. Neueste Einträge stehen immer oben.

Größe anpassen

Die Höhe des History-Panels kann durch Ziehen am oberen Rand (Resize-Handle) angepasst werden (80px bis 500px).

Löschen

Der Clear-Button in der History-Toolbar löscht alle Einträge und den Einzeiler.

11. Annotations

Das Annotations-Panel ermöglicht visuelle Markierungen auf dem Screenshot, ohne den Remote-Desktop zu verändern. Alle Markierungen sind rein lokal im Browser.

Crosshair

Aktivieren Sie die Checkbox Crosshair. Bei jedem Klick auf den Screenshot wird ein Fadenkreuz (gestrichelte horizontale und vertikale Linie) an der angeklickten Position eingezeichnet. Das Crosshair folgt auch der Mausbewegung beim Zeichnen von Bounding Boxes.

Bounding Box

Aktivieren Sie die Checkbox Bounding Box. Dann können Sie durch Klicken und Ziehen auf dem Screenshot Rechtecke zeichnen:

1. Maus drücken — Startpunkt des Rechtecks
2. Maus ziehen — Vorschau des Rechtecks (gestrichelt)
3. Maus loslassen — Rechteck wird fixiert (durchgehende Linie)

Es können beliebig viele Bounding Boxes gezeichnet werden. Sehr kleine Rechtecke (unter 3px Differenz) werden als normaler Klick behandelt.

Farbe

Über den Farbwähler (Farbe) können Sie die Farbe aller Annotationen ändern. Standard ist das Accent-Rot (#e94560). Die Farbe wird sofort auf alle vorhandenen Markierungen angewendet.

Alles löschen

Der Clear-Button entfernt alle Annotations (Crosshair und alle Bounding Boxes).

12. API-Dokumentation

Der desktopkit-server bietet neben der Web UI auch eine vollständige REST-API. Drei Dokumentationsformate sind direkt über die Sidebar verfügbar:

13. Tastenkürzel

Übersicht der Maus- und Tastaturkürzel in der Web UI: