Version: main

Getting Started with keylightd

This guide will help you get started with keylightd, a daemon service for controlling Elgato Key Light devices and potentially other HTTP-based lights with similar interfaces. If you have a similar device that's not explicitly supported, please open a ticket to request support.

Installation

Prerequisites

Linux or macOS operating system (basic testing has been performed on Windows and it should work.)
Go 1.24 or higher (if building from source)
Network connectivity to your Elgato Key Light devices

Option 1: Install via Homebrew (Recommended)

The easiest way to install keylightd is through our Homebrew tap:

brew tap jmylchreest/keylightd
brew install keylightd

This will install both the keylightd daemon and keylightctl CLI tool. The installation automatically sets up a launchd service on macOS and a systemd service on Linux.

To start the service:

brew services start jmylchreest/keylightd/keylightd

Note: You can also run keylightd manually by simply executing keylightd in your terminal if you prefer not to use the system service.

Option 2: Installing from Binary Releases

Download the latest release from the GitHub releases page
Extract the archive:
```
tar -xzf keylightd-v*.tar.gz
```

Move the binary to a directory in your PATH:

sudo mv keylightd /usr/local/bin/
chmod +x /usr/local/bin/keylightd

Option 3: Building from Source

Clone the repository:

git clone https://github.com/jmylchreest/keylightd.git
cd keylightd

Build the binary:
```
go build -o keylightd ./cmd/keylightd
```

Install the binary:

sudo mv keylightd /usr/local/bin/
chmod +x /usr/local/bin/keylightd

Note: After installation, you can run keylightd manually by executing keylightd in your terminal.

Option 4: 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 accss
sudo usermod -a -G keylightd $USER

# Enable and start the service
sudo systemctl enable keylightd
sudo systemctl start keylightd

Socket Permissions: The systemd service creates a Unix socket at /run/keylightd/keylightd.sock that is accessible by users in the keylightd group. This allows keylightctl to communicate with the daemon running as a system service.

Configuration

keylightd uses a configuration file located at ~/.config/keylightd/keylightd.yaml. The configuration file is created when settings are first saved, but you can also create it manually.

Complete Configuration Example

# Application state (automatically managed)
state:
  api_keys:
    - key: "your-generated-api-key-here"
      name: "my-api-key"
      created_at: "2024-01-01T00:00:00Z"
      expires_at: "2024-02-01T00:00:00Z"
      last_used_at: "2024-01-15T12:00:00Z"
  groups:
    group-123451:
      id: "group-123451"
      name: "office-lights"
      lights:
        - "Elgato Key Light ABC1._elg._tcp.local."
        - "Elgato Key Light XYZ2._elg._tcp.local."

# Configuration settings
config:
  # Server configuration
  server:
    # Unix socket path for local communication
    unix_socket: "/run/user/1000/keylightd.sock"

  # HTTP API configuration
  api:
    # Address and port for the HTTP API (default: :9123)
    listen_address: ":9123"

  # Device discovery settings
  discovery:
    # How often to scan for new devices (seconds, default: 30)
    interval: 30
    # How often to check for offline devices (seconds, default: 180)
    cleanup_interval: 180
    # How long before marking a device as offline (seconds, default: 180)
    cleanup_timeout: 180

  # Logging configuration
  logging:
    # Log level: debug, info, warn, error (default: info)
    level: info
    # Log format: text, json (default: text)
    format: text

Creating Your First API Key

The HTTP API requires authentication via API keys. The CLI and Unix socket interfaces do not require API keys — they rely on Unix socket permissions.

Create a key:

keylightctl api-key add my-first-key

This outputs the generated key. Save it — you'll use it in the Authorization header for HTTP requests:

curl -H "Authorization: Bearer YOUR_KEY" http://localhost:9123/api/v1/lights

Managing API keys

You can list, disable, and delete API keys:

keylightctl api-key list
keylightctl api-key disable my-first-key
keylightctl api-key delete my-first-key

Basic Usage

Once the daemon is running and has discovered your lights, you can control them immediately via the CLI:

# List all discovered lights
keylightctl light list

# Turn on a specific light
keylightctl light set "Elgato Key Light ABC1._elg._tcp.local." on true

# Change brightness (0-100)
keylightctl light set "Elgato Key Light ABC1._elg._tcp.local." brightness 50

# Change color temperature (2900-7000 Kelvin)
keylightctl light set "Elgato Key Light ABC1._elg._tcp.local." temperature 4000

Interactive mode

If you omit the light ID or property, keylightctl will prompt you interactively — you don't need to memorize long device IDs.

Desktop Applications

Tray Application

A cross-platform system tray application is available for controlling your lights with a graphical interface. It provides:

System tray icon with dynamic status indication
Brightness and color temperature sliders
Group management
Custom CSS theming with hot reload

Install via AUR (Arch Linux)

yay -S keylightd-tray-bin

Build from Source

cd contrib/keylightd-tray
make build

The binary will be in build/bin/keylightd-tray. See the Tray Application documentation for detailed usage and theming options.

GNOME Extension

There is a GNOME extension available that allows you to control your lights directly from the GNOME desktop. You can download the extension from the GitHub releases page and install it using:

gnome-extensions install keylightd-control@jmylchreest.github.io.zip

After installation, enable the extension through GNOME Extensions or from the command line:

gnome-extensions enable keylightd-control@jmylchreest.github.io

Next Steps

Now that you have keylightd up and running, you can:

Troubleshooting

Lights Not Being Discovered

Ensure your Key Lights are on the same network as your computer
Check that mDNS/Bonjour is not blocked by your firewall
Try running with debug logging: keylightd --log-level debug

Connection Issues

Check that the Key Lights are powered on and connected to your network
Verify network connectivity by pinging the light's IP address
Ensure no firewall is blocking the connection

Socket Permission Issues

If you get a "permission denied" error when using keylightctl with a systemd service:

Error: failed to connect to socket: dial unix /run/keylightd/keylightd.sock: connect: permission denied

This means your user doesn't have permission to access the daemon's socket. To fix this:

Add your user to the keylightd group:
```
sudo usermod -a -G keylightd $USER
```
Log out and back in for the group changes to take effect
Verify you're in the group:
```
groups | grep keylightd
```
Check socket permissions:
```
ls -la /run/keylightd/keylightd.sock
```
The socket should be owned by keylightd:keylightd with group write permissions.

For more help, check the GitHub issues page or submit a new issue.

Installation​

Prerequisites​

Option 1: Install via Homebrew (Recommended)​

Option 2: Installing from Binary Releases​

Option 3: Building from Source​

Option 4: Arch Linux (AUR)​

Configuration​

Complete Configuration Example​

Creating Your First API Key​

Basic Usage​

Desktop Applications​

Tray Application​

Install via AUR (Arch Linux)​

Build from Source​

GNOME Extension​

Next Steps​

Troubleshooting​

Lights Not Being Discovered​

Connection Issues​

Socket Permission Issues​