Direkt zum Hauptinhalt

Systemd-Unit (optional)

Diese Seite gilt nur fuer das Headless-CLI-Binary (chatlix-connect-linux), nicht fuer die Electron-Desktop-App. Die Desktop-App braucht eine aktive grafische Session (X11/XWayland) und ist als GUI-Anwendung nicht dafuer gebaut, unter systemd im Hintergrund ohne Fenster zu laufen — auch mit einer Unit-Datei startet Electron ohne DISPLAY nicht sauber. Wenn du automatischen Start bei Boot willst, nutze konsequent das CLI-Binary aus « Manuelle Installation », Weg B.

Wenn Connect bei jedem Login automatisch starten soll, leg eine User-Systemd-Unit an. Das laeuft im User-Scope (kein root fuer die Unit selbst noetig) und ueberlebt Logout/Login, wenn loginctl enable-linger aktiv ist.

Unit-Datei

Datei: ~/.config/systemd/user/chatlix-connect.service

[Unit]
Description=Chatlix Connect (Headless CLI)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=%h/bin
ExecStart=%h/bin/chatlix-connect-linux
Restart=on-failure
RestartSec=5s
# Verhindert Log-Flut bei Dauer-Crash-Loop:
StartLimitIntervalSec=300
StartLimitBurst=10

[Install]
WantedBy=default.target

%h ist der Home-Pfad des Users. Wichtig: WorkingDirectory muss auf das Verzeichnis zeigen, in dem connect.json liegt — das CLI-Binary sucht seine Config relativ zu sich selbst (dirname(process.execPath)), aber wenn systemd das Working-Directory anders setzt oder das Binary per Symlink gestartet wird, kann das zu Ueberraschungen fuehren. Am sichersten: Binary und connect.json liegen im selben Verzeichnis, und ExecStart/WorkingDirectory zeigen exakt dorthin. Wenn dein Binary woanders liegt, passe beide Pfade an.

Aktivieren

systemctl --user daemon-reload
systemctl --user enable --now chatlix-connect
systemctl --user status chatlix-connect

Die Status-Ausgabe sollte active (running) zeigen. Ob die Verbindung wirklich steht, siehst du nicht im systemd-Status selbst (der zeigt nur "Prozess laeuft"), sondern im Log (naechster Abschnitt) oder im Dashboard unter /dashboard/connect.

Logs ansehen

journalctl --user -u chatlix-connect -f

Das zeigt einen Live-Stream. Mit -n 200 siehst du die letzten 200 Zeilen, mit --since '1 hour ago' einen Zeitfilter.

Journalctl erfasst nur stdout/stderr des Prozesses. Die ausfuehrlicheren Logs mit Timestamps und strukturierten Events liegen zusaetzlich als Datei direkt neben dem Binary unter ~/bin/logs/connect.log (nicht unter ~/.local/share/chatlix-connect/, wie eine aeltere Version dieser Seite behauptete — das CLI-Binary schreibt portabel relativ zu seinem eigenen Pfad, siehe « Status auf Linux »). Bei einem Crash landet zusaetzlich ein strukturierter Report unter ~/bin/crashes/ — die sind lokal-only und werden nicht automatisch hochgeladen, du musst sie bei Support-Anfragen selbst anhaengen.

Auto-Start ohne aktive Session

Standardmaessig laufen User-Units nur, solange du eingeloggt bist (TTY oder GUI). Wenn Connect auch ohne aktive Session laufen soll (z.B. auf einer Streaming-Maschine, die headless bootet):

sudo loginctl enable-linger $USER

Danach startet der User-Service mit dem Boot, unabhaengig von einem Login. Pruefen kannst du das mit:

loginctl show-user $USER | grep Linger

Erwartet: Linger=yes. Ohne aktiven Linger bleibt die Unit "enabled", startet aber erst beim naechsten echten Login — ein haeufiges Missverstaendnis, wenn Connect nach einem Reboot scheinbar grundlos nicht laeuft.

Restart und Stop

systemctl --user restart chatlix-connect
systemctl --user stop chatlix-connect
systemctl --user disable chatlix-connect

Nach einem Binary-Update reicht restart — die Config wird neu eingelesen, das Pairing/der Token bleiben bestehen (die Datei liegt getrennt vom Binary).

Typische Fallstricke

  • Failed to start chatlix-connect.service: Unit not found — User-Bus nicht aktiv oder Unit-Datei am falschen Ort. Pruefe den exakten Pfad ~/.config/systemd/user/chatlix-connect.service, fuehre systemctl --user daemon-reload aus und stelle sicher, dass du als regulaerer User eingeloggt bist (nicht via sudo su -, das haengt an einer anderen Session ohne funktionierenden User-Bus).
  • Restart-Loop — Connect crasht direkt nach Start. In journalctl bzw. logs/connect.log steht meistens ein Auth-Fehler (Token im Dashboard revoked/falsch) oder ein Verbindungsfehler zu wss://ws.chatlix.app/ws (DNS/ausgehende Firewall). Mit ./chatlix-connect-linux doctor im Terminal (Service vorher stoppen) bekommst du eine kompaktere Fehlermeldung als aus dem Journal.
  • Mehrere Sessions gleichzeitig — Wenn du Connect parallel manuell im Terminal startest waehrend die Unit laeuft, verbindet sich die zweite Instanz NICHT zusaetzlich: Connect hat einen Single-Instance-Lock (connect.lock im selben Verzeichnis, PID + Heartbeat-basiert) und verweigert bei einer bereits laufenden Instanz sofort den Start mit der Fehlermeldung "ChatlixConnect läuft bereits" (Exit ohne Verbindungsversuch). Kein flackernder Online/Offline-Status durch doppelte Verbindungen — nur die zuerst gestartete Instanz laeuft wirklich. Willst du die Unit-Instanz durch eine manuelle Terminal-Instanz ersetzen, stoppe zuerst die Unit (systemctl --user stop chatlix-connect), sonst blockiert der Lock den manuellen Start.
  • PATH-/Pfad-Variablen — Systemd-User-Units erben deinen Login-Shell-PATH nicht automatisch. Da das CLI-Binary aber ein einzelnes statisches Executable ohne externe Laufzeit-Abhaengigkeiten ist, betrifft das meist nur eigene Wrapper-Skripte (z.B. wenn du Node.js aus ~/.nvm/... fuer den Game-Watcher-Sourcecode brauchst — der Game-Watcher wird mittlerweile aber ebenfalls als Binary ausgeliefert, siehe « Manuelle Installation »). Schreibe im Zweifel volle Pfade in ExecStart.
  • Falsches Working-Directory — Wenn connect.json nicht neben dem Binary liegt (z.B. weil du das Binary per Symlink aus /usr/local/bin aufrufst), startet Connect im Setup-Modus statt zu verbinden, weil es keine gueltige Config findet. Halte Binary und Config im selben, in der Unit als WorkingDirectory gesetzten Verzeichnis.

Cleanup

systemctl --user disable --now chatlix-connect
rm ~/.config/systemd/user/chatlix-connect.service
systemctl --user daemon-reload

Das Binary und die Konfigurationsdatei bleiben unangetastet — die Unit ist nur der Wrapper. Wenn du Connect komplett entfernen willst, siehe den Deinstallations-Abschnitt in « Manuelle Installation ».