Remote build: a protocol version on the peer link, and may a third-party app send builds?

[Max Gramser (MaxGramser)]

Describe the enhancement

A protocol version on the remote-build peer link, and a word on whether a third-party app may act as an offloader (the side that sends builds) to a Device Builder build server.

I maintain Tessera, a Home Assistant app (add-on) that turns ESP32 touch screens into Home Assistant control panels. Every screen is an ESPHome device: the app writes the screen's YAML into /config/esphome, builds it with a pinned ESPHome (currently 2026.9.0) inside its own container, and installs it over OTA, USB or Web Serial.

We would like Tessera to send its builds to a build server the user already runs (ESPHome Desktop, Device Builder, or esphome-device-builder --remote-build-only), as an offloader on the peer link:

• Only the sending side. The build server stays yours; we would not implement or ship a receiver.
• Pairing like a Device Builder add-on does: the user types the server's host and port (the app has no host network, so no mDNS), compares the fingerprint, and the server approves it. With a headless server, the one-time pairing key.
• submit_job with target: compile and target_esphome_version set to our pinned version, so the receiver provisions exactly the ESPHome our packages need.
• Artifacts back with download_artifacts; the upload stays local, as in Device Builder.
• Any failure, including a protocol error, means the app builds locally and says why. A user is never worse off than today.

What would help from your side:

1. Is a third-party offloader welcome on the peer link? If you would rather we don't, or prefer another route (for example a documented API for submitting a bundle), we will follow that.
2. A protocol version (or a capability list) in the intent_response. The forward-compatible fields work well today, but a version would let a client like ours see that a receiver speaks something newer and fall back to a local build cleanly, instead of failing mid-job. The idea of moving the bundle upload to HTTP (Re-architect peer-link bundle upload onto HTTP POST/PUT instead of chunked WebSocket frames device-builder#2326) is exactly the kind of change a version would make safe for other clients.
3. A bundle the offloader assembles itself. Some of our plugins live in a folder next to /config/esphome, which esphome bundle skips as outside the config directory. Is it fine for an offloader to write the same tarball itself (manifest version 1, every path inside the bundle), or is esphome bundle the only supported producer?

Use cases

The most common request we get is the one remote builds solve: compiling a display firmware with LVGL on a Raspberry Pi 4, or a Pi 5 with 4 GB, takes a long time and sometimes runs out of memory. Today we tell people to open the screen's YAML in Device Builder and press Install there, so their paired build server picks it up. That works, but it builds with the user's ESPHome version instead of the one our packages are tested on, and it skips the app's own steps (for example a small bridge firmware that widens the partition table on 4 MB boards before the real one goes on).

With Tessera as an offloader, the build runs on the user's existing build server with exactly the right ESPHome version, and every step the app does after the build keeps working.

Visual examples

No response

Anything else?

Thanks for remote builds and for documenting the peer link so clearly in API.md and ARCHITECTURE.md; it made it possible to even consider this. We will keep a local build as the fallback whatever the answer is, and adjust to whatever you prefer.