🤖 Headless Servers

The systemd service coolercontrold runs headlessly. The coolercontrol desktop application connects to this daemon. By default, the daemon binds to the local loopback interface (localhost) on port 11987. The web UI is served directly from the daemon at http://localhost:11987/.

If you have a headless server (terminal-only) or want to control another machine remotely, one of the easiest and most secure options is to use an SSH tunnel. Replace user@remote-machine.ip with your remote username/host, and choose any free local port (e.g., 12000):

For example:

ssh -N -L 12000:127.0.0.1:11987 user@remote-machine.ip

This forwards the daemon port on the remote server to your local machine on the chosen local port, e.g. 12000. You can then access the UI in your browser at http://localhost:12000/ (recommended), or point the desktop application to the same address in its daemon connection settings. It will behave as if it were running locally.

TIP

For systems with an NVIDIA GPU, ensure the proprietary driver is installed. CoolerControl uses NVML and the CLI tools nvidia-settings/nvidia-smi when available. On fully headless setups (no Xorg/Wayland), fan control via the CLI tools may not be available.

You can configure the daemon's bind address and port, and point the UI to the same address you have set up or are forwarding. For the daemon, these settings are in the config file /etc/coolercontrol/config.toml, for example:

sudo systemctl stop coolercontrold
sudo nano /etc/coolercontrol/config.toml
sudo systemctl start coolercontrold

[settings]
port = 11987
ipv4_address = "127.0.0.1"
ipv6_address = "::1"

WARNING

Remote access increases risk. Keep the daemon bound to loopback by default. If exposure is necessary, do the following:

• Use a secure transport: SSH port forwarding or a TLS-terminating reverse proxy (TLS termination proxy).
• Enforce strong authentication: set a strong password and rotate it periodically.
• Restrict network reachability: allowlist source IPs and lock down access with host firewall rules/ACLs.
• Avoid binding to all interfaces (e.g., 0.0.0.0) on untrusted networks; prefer a VPN/zero-trust tunnel over direct internet exposure.

---

You can also configure these via environment variables (useful in containerized or ephemeral setups): CC_PORT, CC_HOST_IP4, and CC_HOST_IP6. For example:

export CC_PORT=12000
export CC_HOST_IP4=0.0.0.0
export CC_HOST_IP6=::
sudo systemctl restart coolercontrold

For systemd-managed environments, you can create a drop-in override to persist these settings:

sudo systemctl edit coolercontrold

Then add:

[Service]
Environment = CC_PORT=12000
Environment = CC_HOST_IP4=0.0.0.0
Environment = CC_HOST_IP6=::

Finally, reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart coolercontrold