⚡ gRPC API

CoolerControl provides a gRPC API primarily designed for plugin development and communicating with custom devices. The gRPC API offers strongly-typed, efficient communication with the daemon.

INFO

This API is intended for plugin developers. For applying CoolerControl settings and automation, use the REST API instead.

Overview

Device service plugins expose their own gRPC API to allow CoolerControl to poll and control devices. Plugins can expose the API as either a Unix socket or a TCP socket.

Protocol Buffer Specifications

The complete protocol buffer definitions are available in the cc-plugins repository:

Protocol Buffer Spec

For complete documentation, examples, and templates, see the cc-plugins repository.

Daemon gRPC API

The daemon exposes its own gRPC API for polling device data by default on localhost:11988. This API is read-only and does not offer control capabilities.

Health Checks: The daemon implements the standard gRPC health check service for monitoring.

Health Check Example

You can verify the daemon is running using a health check:

grpcurl --plaintext localhost:11988 grpc.health.v1.Health/Check

Remote Access

To access the gRPC API remotely, configure the daemon's bind address. See TCP Port and Address for configuration details.

Security

The gRPC API does not use TLS by default. For secure remote access, use one of the following methods:

• VPN or secure network - Use Tailscale, Wireguard, or similar solutions
• SSH tunneling - Forward the gRPC port through an SSH connection
• TLS-terminating reverse proxy - Use nginx or similar to handle TLS

Plugin Development

For developing plugins that use the gRPC API, refer to these resources:

• cc-plugins Repository - Plugin development resources, templates, and examples
• Protocol Buffer Spec - Complete proto definitions
• gRPC Documentation - Official gRPC documentation
• Protocol Buffers Guide - Protocol Buffers language guide

See Also

• Plugin Development - Complete plugin development guide
• REST API - REST API reference
• Plugins - User guide for installing plugins
• TCP Port and Address - Configure gRPC port and address