Skip to main content

​
What Is the Nest Cloud Protocol?

The Nest thermostat uses a custom HTTP-based long-poll protocol to communicate with cloud servers. Rather than WebSockets or REST, the device maintains a persistent HTTP connection where the server holds the response open and streams updates to the device using chunked transfer encoding. This protocol was reverse-engineered and documented by Chris Serio (cjserio / @SirHeroic) as the Nest Cloud Protocol Reference. The NoLongerEvil self-hosted server is a Python implementation of this protocol.
The documentation in this section is drawn from revision 2.9 of the Nest Cloud Protocol Reference by Chris Serio. All credit for the underlying protocol research belongs to the original author.

​
Key Concepts

ConceptDescription
Subscribe connectionA persistent HTTP connection where the device waits for server-pushed updates
Server pushThe server wakes a sleeping device by sending data on the open connection
Chunked encodingRequired for server push — allows the server to hold connections open and stream data
BucketsNamed data containers (e.g., device, shared, schedule) that hold thermostat state
WoWLANWiFi Wake-on-LAN — the WiFi hardware keeps the TCP socket alive while the device CPU sleeps

​
Protocol Characteristics

CharacteristicValue
TransportHTTP/1.1 over TLS
EncodingJSON request/response bodies
Connection modelDevice-initiated, server-held open
Push mechanismChunked transfer encoding
Keep-aliveWiFi hardware maintains TCP connection during CPU sleep
Long-poll cycle~290s hold → close → device resubscribes

​
Two Communication Patterns

The protocol has two distinct flows: Subscribe (server → device):
  1. Device POSTs its current bucket state (revisions + timestamps)
  2. Server immediately sends Transfer-Encoding: chunked headers — device offloads connection to WiFi hardware and sleeps
  3. Server holds the connection; when state changes, sends a JSON chunk — device wakes via WoWLAN
  4. Server closes connection after sending; device resubscribes
PUT (device → server):
  1. Device POSTs state changes (user dial adjustment, sensor readings)
  2. Server stores the data, increments revision
  3. Server returns 200 OK with {object_revision, object_timestamp, object_key} — no value field

​
NoLongerEvil Implementation

The NLE self-hosted server implements this protocol on port 8000 (the Device Protocol API). Thermostats connect here automatically after being configured to point at the server. Key implementation differences from Google’s Nest cloud:
  • 3-tier pairing using 7-character entry codes instead of OAuth/JWT
  • SQLite persistence instead of distributed cloud storage
  • No credential provisioning — the server accepts all credentials and identifies devices by serial from Basic Auth
  • Single default structure per device
For the full list of differences, see NLE Differences.

Connection Architecture

Full device lifecycle diagram

Authentication

HTTP Basic Auth and entry key pairing

Transport Mechanism

Subscribe, push, PUT in depth

Bucket System

How device state is organized