Manage Control Plane devices

The Devices tab in the LightNow Control Plane shows where CLI-managed LightNow Proxy clients run and which Runtime Profile each client uses. It is an observed inventory: this release does not assign profiles remotely or push a desired configuration to a device.

What appears in the inventory

A device is created after a successful telemetry-enabled Local Proxy sync. One CLI installation has one stable installation UUID, while every generated client-specific proxy configuration has its own stable client-instance UUID. This allows one machine to report Codex, Claude, Antigravity, Cursor, or VS Code as separate client instances with separate profiles.

LightNow stores the reported hostname, optional display name, platform, registration time, last heartbeat, client and runner versions, profile, and transport. It does not collect IP or MAC addresses, serial numbers, local paths, tool arguments, tool results, authorization headers, or secrets for this inventory.

The device header shows the observed LightNow CLI version and each client row shows the Local Proxy version. When available, both include the installer, latest channel-ready version, and current, outdated, ahead, or unknown status. A stale badge means the reported release check is more than 48 hours old; run lightnow update --check on that device before treating the status as current.

CLI-managed Local Proxy clients only

Direct MCP connections and manually created proxy configurations do not appear unless they use the IDs and telemetry contract generated by LightNow CLI.

Understand presence

Registration creates an offline device without marking it active. LightNow Proxy sends a heartbeat immediately at startup and every 120 seconds after that. A client is active when its last heartbeat is no more than 300 seconds old. A device is active when at least one of its clients is active. Never active means registration succeeded but no heartbeat has arrived yet.

Heartbeat failures do not block MCP requests. They appear in proxy logs and the local status response, and the next regular heartbeat is the only retry.

Inspect local heartbeat diagnostics

lightnow config-status --client codex --json
curl -sS http://127.0.0.1:8080/status | jq '.local_proxy.device_heartbeat'

The /status request applies when the proxy is running in local HTTP mode. For a stdio-started proxy, use its logs and restart the client to trigger the immediate heartbeat.

If local_proxy.telemetry_enabled is false, the CLI does not register the device and the proxy sends neither runtime events nor presence heartbeats.

Plan boundaries

• Free includes one personal device with one client instance.
• Standard allows additional personal devices and supported client instances.
• Enterprise and Enterprise Dedicated enable organization-wide inventory; owners and admins also receive user attribution across the organization.

Registration or inventory access outside these boundaries returns 403 PLAN_UPGRADE_REQUIRED. A personal downgrade does not silently delete existing records: already registered IDs remain observable so they can be reviewed or forgotten, while new device or client IDs require Standard. An organization downgrade retains its inventory but blocks access until Enterprise is active again.

Filter and manage devices

Open Control Plane → Devices. Search by device, user name, or email and filter by status, user, client, or profile. Each device groups all observed client instances and shows their profile, versions, transport, presence, and last-seen time.

• Personal users see and manage only their own devices.
• Organization owners and admins see every organization device with user name and email and may rename or forget them.
• Organization members see, rename, and forget only their own devices.
• A display name changes only the label in LightNow; clearing it restores the reported hostname.
• Only offline devices can be forgotten. An active delete returns 409 DEVICE_ACTIVE.
• If a forgotten device starts again, its stable IDs register it as a new inventory resource.

There is no automatic archival or retention deletion in this release. Forget offline devices explicitly when the inventory record is no longer required.

Device API contract

The scope and user always come from the authenticated request. Clients cannot select or override either value. All path and event identifiers are UUIDs.

Method	Endpoint	Purpose
PUT	/v0.1/integrations/devices/{installationId}/clients/{clientInstanceId}	Idempotently register an offline device/client binding
POST	/v0.1/integrations/devices/{installationId}/clients/{clientInstanceId}/heartbeat	Update observed metadata and presence
GET	/v0.1/integrations/devices	Cursor-paginate visible devices
PATCH	/v0.1/integrations/devices/{deviceResourceId}	Set or clear display_name
DELETE	/v0.1/integrations/devices/{deviceResourceId}	Forget an offline device and its clients

List filters are status, user_id, client_name, profile, search, cursor, and limit. Runtime event ingestion also accepts optional device_installation_id and client_instance_id; older proxies remain valid without them. The complete request and response schemas are published in the Registry API OpenAPI document.

Troubleshoot a missing or offline device

1. Confirm that the client was synced with --local-proxy or --from-settings.
2. Check that telemetry is enabled in the generated proxy configuration.
3. Confirm that the CLI sync completed device registration; a partial sync exits non-zero while leaving the local files intact.
4. Restart the AI client so the generated proxy starts and sends its immediate heartbeat.
5. Inspect local heartbeat diagnostics and Registry reachability.
6. Confirm that the Control Plane is in the same Personal or organization context used by the CLI.
7. If the API reports PLAN_UPGRADE_REQUIRED, verify the plan in that same billing context before retrying the sync.

Use runtime events after presence is healthy to trace requests, latency, and failures.

Use Update LightNow CLI and Proxy to bring an outdated device back to the current release.