Install Kelvin for Philips Hue and Access It Remotely

What Kelvin does for Philips Hue lighting

Kelvin is a small, self-contained home-automation service for supported Philips Hue and compatible lights. Its main purpose is to vary color temperature and brightness throughout the day. Instead of applying one static light setting, Kelvin can use local sunrise and sunset times together with custom intervals that you define.

A typical schedule might use a cooler but moderate setting early in the morning, move toward a daylight-oriented temperature around sunrise, transition to warmer light after sunset, and reduce brightness at night. Those examples describe the intended pattern rather than mandatory values. The exact timing, brightness, and temperature choices remain yours.

Kelvin supports fine-grained daily schedules for individual rooms. It can define a default startup color and brightness, apply gradual transitions, work with smart switches and conventional switches, and activate through a Hue scene or automatically when a light is switched on. It also respects a manual light adjustment until that light is switched off and on again. This behavior lets an intentional temporary change take precedence without permanently replacing the configured schedule.

Kelvin runs on a computer within the same local environment as the Hue bridge. That machine needs to remain on whenever Kelvin should manage the lights. A small always-on system can be suitable, but its operating system and processor must be compatible with either Docker or an available Kelvin release binary.

Prerequisites and deployment decisions

Prepare the local Hue environment before starting the container. Kelvin's documented prerequisites are supported Philips Hue or compatible lights, a configured Philips Hue bridge, and a permanently running computer connected to the network. The bridge should already be operational through its normal local setup before Kelvin attempts discovery and registration.

Hardware and local network requirements

• A configured Philips Hue bridge that is reachable on the local network.
• Supported Hue or compatible lights associated with that bridge.
• A computer that can remain running while lighting automation is needed.
• Docker installed and functioning if you follow the primary installation path in this guide.
• Access to the physical Hue bridge because initial registration requires pressing its blue button.
• A browser on the local network for opening the Kelvin interface.

Docker must be able to pull an image and publish a host port. Confirm Docker itself is working before diagnosing Kelvin. A basic Docker installation check is:

docker version

If that command cannot communicate with the Docker engine, resolve the Docker installation or permissions issue first. Kelvin cannot start until the engine is available.

Choose an appropriate timezone

The documented Docker command passes a timezone through the TZ environment variable. The example uses Europe/Berlin, but you should replace it with the timezone appropriate for the installation location. Correct local time matters because Kelvin's purpose includes time-dependent lighting transitions and local sunrise and sunset behavior.

Do not copy the example timezone merely because it makes the command run. Select the correct timezone identifier for the host location. The Kelvin documentation excerpt supplied for this guide does not enumerate valid timezone values, so this article does not attempt to provide a complete list.

Decide where configuration will persist

Kelvin stores its configuration under /etc/opt/kelvin/ in the container. A container created without persistent storage can run successfully, but its configuration is tied to that container's lifetime. Removing and recreating the container may therefore discard configuration held only inside it.

For a durable installation, map /etc/opt/kelvin/ to a directory on the Docker host. Select a host directory that is included in your normal backup process and protected from unauthorized local access. The directory can contain Kelvin configuration, including the password field described by the project documentation.

Binary installation versus Docker

Kelvin also supports a standalone release-binary workflow. The project instructs users to download the latest archive from its Releases page, extract it, and launch kelvin.exe by double-clicking on Windows or run ./kelvin from a terminal on macOS, Linux, and other Unix-like systems. On first start, Kelvin generates default configuration, discovers a Hue bridge, and begins registration.

This guide uses Docker for the remote-access workflow because the project explicitly documents the Docker web interface as http://{DOCKER_HOST_IP}:8080/. The supplied project evidence does not explicitly establish the browser endpoint for every standalone binary installation. We therefore do not assume that the Docker port and endpoint automatically apply to every binary deployment.

Install Kelvin with Docker

The official Docker workflow is short: pull the image, start a detached container with the local timezone and port mapping, check that Docker reports it as running, and inspect the logs. Complete the steps in that order so that any image, startup, or bridge-registration error remains easy to identify.

docker pull stefanwichmann/kelvin

docker run -d -e TZ=Europe/Berlin -p 8080:8080 stefanwichmann/kelvin

docker ps

docker logs {CONTAINER_ID}

The command above follows the project's documented first-run example. For a long-lived deployment, recreate the container with a Docker bind mount or volume that maps your selected host storage to /etc/opt/kelvin/. Because host paths, ownership, and Docker management tools differ across operating systems, verify the chosen host directory and its permissions rather than copying an arbitrary path.

A generic bind-mount form looks like the following. Replace the timezone and the placeholder host path before running it:

docker run -d \
  -e TZ=Europe/Berlin \
  -p 8080:8080 \
  -v /absolute/host/path:/etc/opt/kelvin/ \
  stefanwichmann/kelvin

Do not run both example containers simultaneously with the same host port. Docker will normally reject the second attempt because host port 8080 is already allocated. If you initially created a temporary container, stop and remove that container before creating the persistent version. Confirm that the mapped directory contains the expected Kelvin configuration after startup.

Pair Kelvin with the Hue bridge

Initial pairing requires local discovery and physical authorization. Kelvin starts by generating a default configuration when one is not already present. It then looks for a bridge on the local network. When it finds one and begins user registration, the log asks you to push the blue button on the Hue bridge.

After successful registration, test Kelvin with a small set of lights before applying broad household changes. Switching a managed light off and on provides a practical way to observe how Kelvin reacts. Remember that manual changes are respected until the light is switched off and on again, so a manually overridden light may not immediately demonstrate the currently scheduled state.

Configure lighting schedules through the web interface

Open http://{DOCKER_HOST_IP}:8080/ from a browser that can reach the Docker host. The interface requests a password and accepts any username. Kelvin generates the password on first start. Retrieve it from the startup log:

docker logs {CONTAINER_ID}

The password is also available in the password field of config.json. If configuration storage is mapped to the host, protect that file as a credential-bearing configuration file.

Kelvin's documented capabilities include defining fine-grained daily schedules for each room, setting default startup color and brightness, and coordinating changes with sunrise and sunset. Use the web interface to adapt the default configuration to your household. Plan the desired behavior before editing:

• Identify which rooms Kelvin should manage.
• Decide how brightness and color temperature should vary through the morning, daytime, evening, and night.
• Choose whether Kelvin should activate through a Hue scene or automatically when lights are switched on.
• Set sensible startup behavior for lights returning from an off state.
• Confirm that the configured location and timezone correspond to the physical installation.
• Make small changes first and observe at least one normal transition cycle.

The available project evidence confirms these capabilities but does not provide a complete field-by-field specification of the current web interface. Labels and controls may vary by release. For that reason, this guide does not invent menu names, schedule syntax, brightness ranges, temperature units, or save buttons that are not established by the evidence.

docker restart {CONTAINER_ID}

Understand manual overrides

Kelvin respects manual light changes until the affected light is switched off and on again. This is useful when someone temporarily wants different lighting, but it can also make schedule testing confusing. If a light does not adopt the expected scheduled state, determine whether it was manually changed. Cycle it off and on, then observe Kelvin again.

Validate gradual transitions carefully

Kelvin is designed to apply gradual transitions that are not intrusive. Do not conclude that a schedule failed merely because there was no immediate dramatic change. Check the configured time interval, current light state, room assignment, manual-override behavior, and log output. During testing, use clearly distinguishable but comfortable settings and avoid values that could disturb other occupants.

Verify the complete local installation

Remote access should only be added after local verification succeeds. This separation is important because a tunnel cannot repair a stopped container, unsuccessful Hue registration, incorrect schedule, missing password, or inaccessible local web listener.

The v1.3.9 release information mentions a health endpoint for container monitoring, but the supplied evidence does not establish its path or response contract. Do not guess a URL for monitoring. Use the documented root interface, container status, application logs, and actual Hue behavior unless you independently confirm the health-endpoint details for the installed release.

Access Kelvin remotely with a Localtonet HTTP tunnel

After the Docker deployment works locally, Localtonet can publish the Kelvin web interface through an HTTP tunnel. Our client establishes an outbound connection to a Localtonet relay server, so the setup does not require inbound router port forwarding, firewall changes, VPN configuration, or a public IP address.

The tunnel points to the already working local service. In this deployment, that service is the Docker host on port 8080. If the Localtonet client runs on the Docker host, the local target may be 127.0.0.1 and port 8080, provided the client can reach that listener. If the client runs on another device, use the Docker host's reachable local IP address and port 8080.

Everything can be managed from the Localtonet dashboard or REST API, but this guide does not invent API endpoints or authentication examples. For the current product workflow, consult the Localtonet documentation.

Test from a genuinely external network

A browser on the same Wi-Fi network may not demonstrate the complete remote path. After starting the tunnel, test its public HTTPS address from a mobile connection or another external network. Verify that the login prompt appears before configuration data is displayed. Then authenticate and perform a low-impact operation, such as reviewing the configured schedule.

Avoid making disruptive lighting changes during the first remote test. Connectivity, authentication, and application behavior should be tested separately. If the page does not load, first determine whether the failure is local, at the Localtonet client, or in the tunnel configuration.

Routine operation, restarts, persistence, and updates

Check whether Kelvin is running

Use docker ps for a quick status check. If the container is not present, use Docker's container listing and inspect its logs to determine whether it stopped. The normal local web interface depends on the Kelvin container, while remote access additionally depends on the Localtonet client and HTTP tunnel.

docker ps
docker logs {CONTAINER_ID}

Restart after configuration changes

Kelvin requires a restart after configuration changes. Restart through the web interface when that option is available, or use the documented Docker command:

docker restart {CONTAINER_ID}

After restarting, inspect the logs and reload the web interface. Confirm bridge connectivity, location handling, and cyclic updates instead of assuming that a successful Docker restart means the application accepted every setting.

Back up persistent configuration

If /etc/opt/kelvin/ is mapped to the host, include the mapped directory in a protected backup routine. Treat backups as sensitive because configuration may contain the web-interface password. Test restoration on a noncritical instance or during a planned maintenance window before relying on it.

A bind mount preserves data only if it points to the intended directory and the container can read and write it. After recreating a container, confirm that the previous schedule and password remain present. An empty interface or newly generated default configuration may indicate that the wrong host path was mounted.

Approach image updates cautiously

Pulling the image again can retrieve a newer available build, but replacing a running container is an operational change. Preserve configuration first, review the project release notes, and record the currently working deployment details. This guide does not claim that every release is compatible with every previous configuration or prescribe an unattended update policy.

Kelvin advertises an auto-upgrade capability, but a containerized environment still deserves deliberate change control. Verify behavior after any upgrade, particularly bridge registration, room schedules, local access, authentication, and the Localtonet target.

Understand the two independent service lifecycles

Troubleshooting Kelvin and remote access

The image does not download

Run docker version and confirm that the Docker engine is available. Then retry docker pull stefanwichmann/kelvin. Errors at this stage concern Docker connectivity, image retrieval, host permissions, or platform compatibility rather than Hue pairing or Localtonet.

The container is not shown by docker ps

A container that exits is omitted from the default running-container list. Inspect Docker's full container list and read its logs. Do not create repeated replacement containers without understanding the original failure, especially if each attempt generates separate configuration.

Docker reports that port 8080 is already allocated

Another process or container is already using host port 8080. Identify that process before changing the mapping. Although Docker can publish a different host port, this guide bases the Localtonet workflow on the documented 8080:8080 deployment. If you deliberately choose another host port, verify the resulting local URL and use that verified host port as the tunnel target.

Kelvin does not find the Hue bridge

Confirm that the bridge is configured and available on the local network, and that the Docker host is connected to the appropriate network. Review the Kelvin log for the exact discovery state. The supplied evidence does not document alternative bridge-address settings or Docker network modes, so this article does not prescribe unverified flags. Resolve local discovery before attempting remote access.

The blue-button registration times out

Kelvin waits one minute for the physical button press. Restart the registration attempt, watch the log, and press the blue button when requested. Pressing it long before or after the registration prompt may not complete the intended authorization.

The web-interface password is unknown

Inspect the startup log with docker logs {CONTAINER_ID}. Kelvin generates the password on first start and also stores it in the password field of config.json. If neither location contains the expected persistent configuration, check whether the correct host directory is mapped to /etc/opt/kelvin/.

The browser cannot open the local interface

First confirm that the container is running and that Docker published host port 8080. Test from the Docker host, then from another device using http://{DOCKER_HOST_IP}:8080/. A failure on the Docker host indicates a local container or listener problem. Success on the host but failure from another LAN device points to address selection, host firewall policy, or local-network reachability.

The schedule appears not to affect a light

Check whether the light supports the relevant Kelvin functionality, belongs to the expected room, is currently on, and was manually adjusted. Kelvin respects manual changes until the light is switched off and on again. Also verify timezone, detected location, current schedule interval, and the application log.

The public URL fails while the local interface works

Confirm that the Localtonet client is connected, the correct device token is selected, the relay server is available, and the HTTP tunnel has actually been started. Then verify the local target from the Localtonet client device itself. If the client is on another computer, 127.0.0.1 refers to that computer rather than the Docker host, so use the Docker host's reachable LAN address.

The public page opens but authentication fails

Verify the generated Kelvin password from the protected startup log or config.json. The project documentation says the interface accepts any username, so focus on the password and whether a new configuration was generated. If the password changed unexpectedly, examine configuration persistence before resetting or recreating anything.

Remote access stops unexpectedly

Check each dependency independently: Kelvin container status, local port 8080, Localtonet client connectivity, and tunnel status. A Localtonet tunnel is available only while the selected client device is connected and the tunnel is running. Creating a tunnel configuration alone does not keep it active.

Frequently asked questions