README
¶
keylightd
keylightd is a daemon and CLI tool for managing Key Lights on your local network. While designed primarily for Elgato Key Lights, it may also support other HTTP-based lights with similar interfaces (if you have a compatible device not explicitly supported, please open a ticket).
GNOME Extension
The keylightd GNOME Extension provides convenient desktop control for your Key Lights and is available in the contrib/gnome-extension directory, from the releases page here, or from the GNOME extensions website here
| Lights On | Lights Off |
|---|---|
 |
 |
| Extension panel showing lights in the on state | Extension panel showing lights in the off state |
Features
- Automatic discovery of lights via mDNS
- Grouping of lights for batch control
- HTTP REST API for remote control
- Unix socket and CLI interface for local control
Components
- keylightd: Daemon that discovers lights, persists configuration, and exposes APIs
- keylightctl: CLI tool for managing lights and groups
graph LR
A[keylightctl] ---|Unix Socket| B[keylightd]
D[gnome-extension] ---|HTTP| B
B ---|mDNS/HTTP| C[Key Lights]
Quick Start
Download the latest release binaries and run:
# Start the daemon
./keylightd
# List discovered lights
./keylightctl light list
# Create a light group
./keylightctl group add "Office"
# Control a light group
./keylightctl group set Office on true
Configuration files are automatically generated on first save in ~/.config/keylightd/.
Installation Methods
Homebrew (macOS/Linux)
Install via Homebrew using our official tap:
# Add the tap
brew tap jmylchreest/keylightd
# Install keylightd
brew install keylightd
Or install directly:
brew install jmylchreest/keylightd/keylightd
This installs both keylightd and keylightctl binaries plus a service to run the daemon.
Arch Linux (AUR)
You can install it via AUR on Arch (package name is keylightd-bin). Add your user to the keylightd group to access the socket via CLI:
# Install via AUR helper (such as yay or paru)
paru -S keylightd-bin
# Add user to group for socket access
sudo usermod -a -G keylightd $USER
# Enable and start the service
sudo systemctl enable keylightd
sudo systemctl start keylightd
Documentation
For detailed documentation, see github pages
Contributing
PRs and issues are welcome! Please ensure all tests pass and code is formatted.
License
MIT License - see the LICENSE file for details.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
keylight-openapi
command
Package main provides a CLI tool to generate the OpenAPI specification for the keylightd API.
|
Package main provides a CLI tool to generate the OpenAPI specification for the keylightd API. |
|
keylightctl
command
|
|
|
keylightd
command
|
|
|
contrib
|
|
|
keylightd-tray
command
|
|
|
internal
|
|
|
events
Package events provides a lightweight in-process event bus for broadcasting state changes to subscribers (e.g., WebSocket hub, future SSE endpoint).
|
Package events provides a lightweight in-process event bus for broadcasting state changes to subscribers (e.g., WebSocket hub, future SSE endpoint). |
|
http/handlers
Package handlers provides typed Huma request/response structs and handler implementations for the keylightd HTTP API.
|
Package handlers provides typed Huma request/response structs and handler implementations for the keylightd HTTP API. |
|
http/mw
Package mw provides middleware and registration helpers for the keylightd HTTP API.
|
Package mw provides middleware and registration helpers for the keylightd HTTP API. |
|
http/routes
Package routes provides shared route registration for the keylightd HTTP API.
|
Package routes provides shared route registration for the keylightd HTTP API. |
|
logging
Package logging provides filter validation and setup helpers for the keylightd structured logging system backed by slog-logfilter.
|
Package logging provides filter validation and setup helpers for the keylightd structured logging system backed by slog-logfilter. |
|
ws
Package ws provides a WebSocket hub for broadcasting real-time events to connected clients.
|
Package ws provides a WebSocket hub for broadcasting real-time events to connected clients. |
|
pkg
|
|
|
keylight
Concurrency Notes (audit): - Read operations (GetDiscoveredLights, GetLights) use RLock and return snapshots (map/slice copies or new structs) to avoid external mutation of internal state.
|
Concurrency Notes (audit): - Read operations (GetDiscoveredLights, GetLights) use RLock and return snapshots (map/slice copies or new structs) to avoid external mutation of internal state. |