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

1. Download the latest release from the GitHub releases page
2. Extract the archive:

   tar -xzf keylightd-v*.tar.gz

3. 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

1. Clone the repository:

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

2. Build the binary:

   go build -o keylightd ./cmd/keylightd

3. 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:

• Explore light control options
• Create and manage light groups
• Review the complete API reference

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:

1. Add your user to the keylightd group:

   sudo usermod -a -G keylightd $USER

2. Log out and back in for the group changes to take effect

3. Verify you're in the group:

   groups | grep keylightd

4. 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.