Case study

TeddyCloud: a self-hosted replacement for the Toniebox cloud

Reimplements the Boxine cloud services a Toniebox talks to as a self-hosted C server, so the box can fetch audio, settings and over-the-air content locally while the owner controls what reaches the manufacturer. It serves and caches tonie audio, converts other audio into the box’s TAF format, can pass requests through to the original cloud, and adds a web interface, MQTT and Home Assistant integration. Protobuf definitions in the repository describe the box’s freshness-check, RTNL log and TAF header messages.

Requirements & limits

Reviewed at the stable master head of 2026-08-25, the v0.7.0 merge; release tc_v0.7.0 was tagged the same day, and active development continues on the develop branch. The project’s setup guide covers Toniebox 1 boxes with CC3200, CC3235 or ESP32 chips, and the README lists Toniebox 2 support as planned.
Setup is invasive and specific to each box: the project guide has owners dump their own box’s client certificates, flash a replacement CA into the box and redirect its DNS, and the server can extract or inject certificates in an ESP32 firmware dump. The repository ships no box certificates, firmware or tonie audio (those directories are empty placeholders), and this record gives no extraction or flashing steps. The dev-sandbox’s pre-generated certificates are self-signed and meant only for local testing.
Builds with a hand-written Makefile, protoc-c and a C toolchain, plus submodules for CycloneTCP/SSL/Crypto, cJSON, Opus, Ogg, the teddycloud_web frontend and emsdk; Linux debug builds enable AddressSanitizer and UBSan, and Docker is the recommended path on macOS. Release tc_v0.7.0 attaches an amd64 zip from the Windows/Linux release workflow, and Debian, Ubuntu and Alpine Docker images are published for several platforms. Stream conversion uses ffmpeg.
Python API tests for the custom-tonie JSON endpoints and a WASM TAF-encoder test run through Makefile targets; the reviewed workflows build and publish without running them. A dev-sandbox serves mock tonies, box and TAF data. Behavior with real boxes and the Boxine cloud remains project-reported, and this source review ran nothing.
GPL-2.0 (LICENSE); the vendored Cyclone stack, Opus, Ogg, cJSON and FatFs keep their own terms. Tonie audio, box firmware and Boxine’s services keep their own rights. The reviewed sources establish no AI or REA use.

About this entry

Type: Case study
Category: Independent reconstruction cases
Relationship: Independent reconstruction project
Targets: Firmware · Protocol

Sources reviewed 2026-10-19

The description was reviewed against primary sources. This does not establish runtime testing, security auditing or verified compatibility.

Report an outdated entry Suggest a translation fix

Primary sources

README.md GitHub · toniebox-reverse-engineering/teddycloud · Revision 78c3b38
CONTRIBUTING.md GitHub · toniebox-reverse-engineering/teddycloud · Revision 78c3b38
.gitmodules GitHub · toniebox-reverse-engineering/teddycloud · Revision 78c3b38
Makefile GitHub · toniebox-reverse-engineering/teddycloud · Revision 78c3b38
proto GitHub · toniebox-reverse-engineering/teddycloud · Revision 78c3b38
contrib/certs GitHub · toniebox-reverse-engineering/teddycloud · Revision 78c3b38
dev-sandbox/README.md GitHub · toniebox-reverse-engineering/teddycloud · Revision 78c3b38
tests/test_tonies_custom_json_api.py GitHub · toniebox-reverse-engineering/teddycloud · Revision 78c3b38
.github/workflows/build_release.yml GitHub · toniebox-reverse-engineering/teddycloud · Revision 78c3b38
.github/workflows/publish_docker_matrix_base.yml GitHub · toniebox-reverse-engineering/teddycloud · Revision 78c3b38
LICENSE GitHub · toniebox-reverse-engineering/teddycloud · Revision 78c3b38
https://github.com/toniebox-reverse-engineering/teddycloud/releases/tag/tc_v0.7.0
https://tonies-wiki.revvox.de/docs/tools/teddycloud/setup/

Requirements & limits

About this entry

Primary sources

More in Firmware and hardware