esp-rainmaker is the firmware half of Espressif's zero-configuration cloud for ESP32

The four components and which one this repository is

ESP RainMaker is described as an end-to-end solution offered by Espressif to enable remote control and monitoring for products based on the ESP32 series of SoCs without any configuration required in the Cloud. The README names the covered parts: the ESP32, ESP32-S2, ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C6, ESP32-H2, and ESP32-C5 which it marks as preview.

The solution has four primary components, and the README is careful to say which is which. The Claiming Service is where you get the Cloud connectivity credentials. The RainMaker Agent is this repository, and the README says in parentheses that it is what you use to develop the firmware. The RainMaker Cloud is the backend offering remote connectivity. And the RainMaker Phone App or CLI are the client utilities for remote access.

So the repository is the device side. It is a C component that you clone, add to your ESP-IDF project and link into your firmware, and it is what talks to the Claiming Service and the Cloud on your device's behalf.

The three key features explain why the design is unusual. You can define your own devices and parameters, of any type, in the firmware. There is zero configuration required on the Cloud. And the phone apps dynamically render the UI as per the device information.

That third point is the one that changes how you build. The app is not configured per product by a designer; it discovers the device model from the cloud, which is what the firmware-defined parameters make possible. The cost is that the schema of your device model is a contract with the app rendering, and the app's ability to render a given parameter type is not something the README documents.

Cloning with submodules, because the build will fail without them

The installation instruction is short, and the README spends a sentence on the option that matters.

git clone --recursive https://github.com/espressif/esp-rainmaker.git

The note after it says the --recursive option is required to pull in the various dependencies into esp-rainmaker, and gives the repair command for anyone who already cloned without it, which is git submodule update --init --recursive.

That repair command matters more than it looks, because the repository root contains a .gitmodules file, which is the visible sign of a project that depends on other repositories being checked out at specific points in history. A plain clone of this repository gives you source that does not compile, and the error you get is likely to point at a missing header rather than at the submodule you forgot.

The rest of the setup is a documentation pointer rather than a command list. The README asks you to check the ESP RainMaker documentation at the get started page to get going, and says each example has its own README with additional information about using that example. That second point is the practical instruction for anyone evaluating the agent, because the examples are the closest thing to a reference application.

The examples directory in the repository is broad. There is camera, ethernet_switch, fan, gpio, homekit_switch, led_light, m5_demos, matter, multi_device, rainmaker_controller, switch, temperature_sensor, thread_br and zigbee_gateway, alongside a common directory. The presence of thread_br and zigbee_gateway says the agent is expected to sit underneath protocol bridges, and matter and homekit_switch show it being used where the device has to appear in a smart home ecosystem.

ESP-IDF 4.x is no longer supported on this branch

The first thing in the README is a warning, and it is the kind of warning that catches people out:

This branch will not support esp-idf v4.x releases anymore as they have reached their end of life. Please check out idf_4_x_compat branch if your project requires it.

So there are two lines of development with different audiences. The master branch is for current work, and the idf_4_x_compat branch exists for projects still on the older toolchain. The README separately states that ESP RainMaker can work with ESP IDF 4.1 and above, which is the supported version range as documented.

These two statements need to be read together carefully. The 4.1 and above figure describes the compatibility of the codebase, and the branch warning describes which branch carries that support. A project on ESP-IDF 4.1 or 4.4 therefore needs the compat branch, not master, and the version statement does not mean master works with 4.1.

For anyone planning an adoption, the version floor and the branch are the first two things to settle, because they determine which source you build against and which of the two trees you will be following. Switching branches later is not a small operation, since the submodules and the ESP-IDF dependency versions move with them.

The repository also has a CHANGES.md file, and the README points to it for major changes, which is where you look before a long-running project takes a branch switch.

The phone apps are the user interface, and they are separate repositories

The client side of RainMaker is the part a product team actually touches, and the README documents where each app comes from.

For Android there are three routes: the Google PlayStore listing, a direct APK linked to the project wiki, and the source code in a separate repository, esp-rainmaker-android. For iOS there are two: the Apple App Store listing and the source in esp-rainmaker-ios.

The open sourcing of both clients is the detail that matters for a product team, and it is worth stating plainly why. The RainMaker apps render their UI dynamically from the device information the cloud holds about your product. That means your device model, its parameters and their types are effectively the app's input. If you ship a product on RainMaker, you are relying on a rendering behaviour defined in Espressif's client code, and being able to read that code, or fork it, is what lets you predict what your customer will see.

The CLI variant of the client utilities is mentioned in the components list but the README does not describe it in the same detail as the phone apps, so treat it as a documented component whose interface you will have to look up rather than one this page describes.

Community support runs through the ESP32 Forum and a Gitter chat, both linked from the README, and the README also points at an ESP Launchpad page for trying the solution on that hardware.

Where the zero-configuration promise strains

The design goal is zero configuration on the Cloud, and the mechanism is that the device declares itself. That is genuinely convenient for a maker or a small product team, and it is the right trade for the common case of a handful of parameters on a device that has just been manufactured.

The strain appears when the product grows. The README lists the ability to define own devices and parameters, of any type, in the firmware as a key feature, and a device with a large parameter set or a complex type is a design that has to be understood by the app's renderer, which is not documented here. A firmware-defined type that the app does not know how to render will not fail loudly; it will render as something uninteresting.

The second strain is the vendor dependency. The Cloud is Espressif's, the app behaviour is Espressif's, and the credentials come from Espressif's Claiming Service. There is no self-hosted option in the components list, and the repository has no Docker or deployment configuration, because there is nothing here to deploy. A team whose requirement is that the device backend sits inside its own network cannot satisfy it with this stack, and the natural alternative, running your own MQTT broker and your own device management, is a different architecture with a different amount of work.

The third strain is the branch policy. The master branch has dropped ESP-IDF 4.x, and the idf_4_x_compat branch exists to carry it. That is a reasonable way to manage end-of-life toolchains, but it means a long-lived product on an older ESP-IDF is running against a branch that receives no new work, and the README does not say how long that will hold.

One more thing to check rather than assume: the repository has no GitHub releases, so there is no tagged version to pin, and the last push was on 2026-10-12.

Editorial conclusion

Adopt esp-rainmaker if you are building an ESP32 product and want remote control and monitoring with the device model declared in firmware rather than in a cloud console, since zero configuration on the Cloud side is the design goal and the phone apps render the UI from the device information. Do not adopt it if you need a self-hosted backend, because the Cloud is Espressif's and the phone apps are tied to it, and do not stay on the master branch if your project is on ESP-IDF 4.x, since that branch has dropped support for those releases. Verify first that the ESP-IDF version you build against is 4.1 or above, that you cloned with the recursive option so the submodules are present, that your board is one of the listed ESP32 variants, and that the parameter and device definitions you write in firmware match what the app expects to render.

Frequently asked questions

Official sources

1. espressif/esp-rainmaker on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README