Zum Hauptinhalt springen

Control-Plane-Geräte verwalten

Der Tab Devices in der LightNow Control Plane zeigt, wo durch die CLI verwaltete LightNow-Proxy-Clients laufen und welches Runtime Profile jeder Client verwendet. Es handelt sich um ein beobachtetes Inventar: Dieses Release weist keine Profile remote zu und verteilt keinen Desired State an Geräte.

Was im Inventar erscheint​

Ein Gerät entsteht nach einem erfolgreichen Local-Proxy-Sync mit aktivierter Telemetrie. Eine CLI-Installation besitzt eine stabile Installations-UUID, während jede generierte clientspezifische Proxy-Konfiguration eine eigene stabile Client-Instanz-UUID erhält. So kann ein Rechner Codex, Claude, Antigravity, Cursor oder VS Code als getrennte Client-Instanzen mit getrennten Profilen melden.

LightNow speichert gemeldeten Hostnamen, optionalen Anzeigenamen, Plattform, Registrierungszeit, letzten Heartbeat, Client- und Runner-Versionen, Profil und Transport. Für dieses Inventar werden keine IP- oder MAC-Adressen, Seriennummern, lokalen Pfade, Tool-Argumente, Tool-Ergebnisse, Authorization-Header oder Secrets erfasst.

Der Geräteheader zeigt die beobachtete LightNow-CLI-Version, jede Client-Zeile die Local-Proxy-Version. Sofern verfügbar erscheinen Installer, aktuelle Zielversion und current, outdated, ahead oder unknown. Check stale bedeutet, dass die letzte Release-Prüfung mehr als 48 Stunden zurückliegt.

Presence verstehen​

Die Registrierung erzeugt ein Offline-Gerät, ohne es aktiv zu markieren. LightNow Proxy sendet direkt beim Start und danach alle 120 Sekunden einen Heartbeat. Ein Client ist active, wenn sein letzter Heartbeat höchstens 300 Sekunden alt ist. Ein Gerät ist active, wenn mindestens einer seiner Clients active ist. Never active bedeutet, dass die Registrierung erfolgreich war, aber noch kein Heartbeat eingegangen ist.

Heartbeat-Fehler blockieren keine MCP-Requests. Sie erscheinen in Proxy-Logs und im lokalen Status; der nächste reguläre Heartbeat ist der einzige Retry.

Lokale Heartbeat-Diagnose prüfen
lightnow config-status --client codex --json
curl -sS http://127.0.0.1:8080/status | jq '.local_proxy.device_heartbeat'

Der /status-Request gilt für einen im lokalen HTTP-Modus laufenden Proxy. Bei einem per stdio gestarteten Proxy nutze dessen Logs und starte den Client neu, um den sofortigen Heartbeat auszulösen.

Ist local_proxy.telemetry_enabled auf false gesetzt, registriert die CLI das Gerät nicht und der Proxy sendet weder Runtime-Events noch Presence-Heartbeats.

Plangrenzen​

  • Free umfasst ein persönliches Gerät mit einer Client-Instanz.
  • Standard erlaubt weitere persönliche Geräte und unterstützte Client-Instanzen.
  • Enterprise und Enterprise Dedicated aktivieren das organisationsweite Inventar; Owner und Admins erhalten zusätzlich die Benutzerzuordnung über die gesamte Organisation.

Registrierung oder Inventarzugriff außerhalb dieser Grenzen liefert 403 PLAN_UPGRADE_REQUIRED. Ein persönlicher Downgrade löscht vorhandene Datensätze nicht stillschweigend: Bereits registrierte IDs bleiben sichtbar, damit sie geprüft oder vergessen werden können; neue Geräte- oder Client-IDs benötigen Standard. Bei einem Organisations-Downgrade bleibt das Inventar erhalten, ist aber bis zur erneuten Aktivierung von Enterprise gesperrt.

Geräte filtern und verwalten​

Öffne Control Plane → Devices. Suche nach Gerät, Benutzername oder E-Mail und filtere nach Status, Benutzer, Client oder Profil. Jedes Gerät gruppiert alle beobachteten Client-Instanzen und zeigt Profil, Versionen, Transport, Presence und den letzten Kontakt.

  • Persönliche Benutzer sehen und verwalten ausschließlich eigene Geräte.
  • Organisations-Owner und -Admins sehen alle Organisationsgeräte mit Benutzername und E-Mail und dürfen sie umbenennen oder vergessen.
  • Organisations-Members sehen, benennen und vergessen ausschließlich eigene Geräte.
  • Ein Anzeigename ändert nur das Label in LightNow; Leeren stellt den gemeldeten Hostnamen wieder her.
  • Nur Offline-Geräte können vergessen werden. Ein aktiver Delete liefert 409 DEVICE_ACTIVE.
  • Startet ein vergessenes Gerät erneut, registrieren seine stabilen IDs eine neue Inventar-Resource.

Dieses Release archiviert oder löscht Inventardaten nicht automatisch. Vergiss Offline-Geräte ausdrücklich, sobald der Inventardatensatz nicht mehr benötigt wird.

Device-API-Vertrag​

Scope und Benutzer stammen immer aus dem authentifizierten Request. Clients können keinen der beiden Werte wählen oder überschreiben. Alle Pfad- und Event-IDs sind UUIDs.

MethodeEndpointZweck
PUT/v0.1/integrations/devices/{installationId}/clients/{clientInstanceId}Offline-Bindung aus Gerät und Client idempotent registrieren
POST/v0.1/integrations/devices/{installationId}/clients/{clientInstanceId}/heartbeatBeobachtete Metadaten und Presence aktualisieren
GET/v0.1/integrations/devicesSichtbare Geräte per Cursor paginieren
PATCH/v0.1/integrations/devices/{deviceResourceId}display_name setzen oder leeren
DELETE/v0.1/integrations/devices/{deviceResourceId}Offline-Gerät und seine Clients vergessen

Listenfilter sind status, user_id, client_name, profile, search, cursor und limit. Runtime-Event-Ingestion akzeptiert zusätzlich optionale Felder device_installation_id und client_instance_id; ältere Proxies bleiben ohne diese Felder gültig. Vollständige Request- und Response-Schemas stehen im OpenAPI-Dokument der Registry API.

Ein fehlendes oder Offline-Gerät untersuchen​

  1. Bestätige, dass der Client mit --local-proxy oder --from-settings synchronisiert wurde.
  2. Prüfe, ob Telemetrie in der generierten Proxy-Konfiguration aktiviert ist.
  3. Bestätige, dass der CLI-Sync die Device-Registrierung abgeschlossen hat; ein partieller Sync endet fehlerhaft und lässt lokale Dateien bestehen.
  4. Starte den AI-Client neu, damit der generierte Proxy startet und seinen sofortigen Heartbeat sendet.
  5. Prüfe lokale Heartbeat-Diagnose und Registry-Erreichbarkeit.
  6. Bestätige, dass die Control Plane denselben Personal- oder Organisationskontext wie die CLI verwendet.
  7. Liefert die API PLAN_UPGRADE_REQUIRED, prüfe vor dem nächsten Sync den Plan in genau diesem Billing-Kontext.

Nutze Runtime-Events, nachdem Presence gesund ist, um Requests, Latenz und Fehler zu verfolgen.

Mit LightNow CLI und Proxy aktualisieren bringst du ein veraltetes Gerät auf den aktuellen Release-Stand.