teddycloud

teddycloud

Docker app from CatDuck's Repository

teddyCloud is an alternative server for your Toniebox, allowing you to host the cloud services locally.

Overview
teddyCloud is an alternative server for your Toniebox, allowing you to host the cloud services locally. This gives you control over which data is sent to the original manufacturer's cloud, and lets you host your own figurine audio files on your NAS or any other server. A Toniebox only connects on port 443 and this cannot be changed. If the Unraid web interface or another container already uses port 443, set Network Type to a custom network (such as br0) and give TeddyCloud its own IP address. Your Toniebox must be set up to use this server and its certificates must be placed in the certs folder; follow the TeddyCloud guide: https://toniebox-reverse-engineering.github.io/docs/tools/teddycloud/ The web interface has an optional login that is off by default. Do not expose TeddyCloud to the internet.

TeddyCloud

Features

TeddyCloud is an alternative server for your Toniebox, allowing you to host the cloud services locally. This gives you the control about which data is sent to the original manufacturer's cloud and allows you to host your own figurine audio files on e.g. your NAS or any other server.

Currently implemented are:

  • Provide audio content over the air
  • Cache original tonie audio content
  • Simulate live content (.live)
  • Passthrough original tonie audio content
  • Convert any audio file to a tonie audio file (web)
  • On-the-fly convert audio streams via ffmpeg for webradio and streams
  • Basic Web fronted
  • Filter custom tags to prevent deletion (.nocloud)
  • Configure maximum volume for speaker and headphones
  • Configure LED
  • Configure slapping
  • Customize original box sounds (ex. jingle) over the air
  • Extract/Inject certitifcates on a esp32 firmware dump
  • Decode RTNL logs
  • MQTT client
  • Home Assistant integration (MQTT)
  • Optional web UI login (disabled by default; enable in the web interface)
  • Web frontend (full stack developers welcome)

Planned

  • teddyBench integration
  • Toniebox 2 support

Web UI login

Login protection is off by default. When enabled, the web interface requires a username and password; Toniebox cloud APIs on the box port are unchanged.

  • Create users and turn login on in the web UI (Settings).
  • Users are stored as salted SHA-256 hashes in web_users.json under the config directory.
  • After five failed logins from the same IP, further attempts are blocked for 10 minutes.
  • Set TEDDYCLOUD_WEB_AUTH_DISABLE=1 to bypass login (for recovery).
  • Removing web_users.json (no users left) turns login protection off again.
  • Still not recommended for public exposure: the login only protects the web UI. The direct APIs are still unprotected, so do not host TeddyCloud publicly unless you know how to secure a self-hosted service (for example behind a VPN or an authenticating reverse proxy). TeddyCloud does not treat LAN and reverse-proxy traffic differently (a proxy often looks like a local client).

A Traefik example that separates the web UI (HTTP) from the Toniebox port (TLS passthrough) is in docker/docker-compose.traefik.example.yaml.

Where to start?

If you want to get started, please follow our guide on our website.

Docker images and release candidates

Docker images are published to ghcr.io/toniebox-reverse-engineering/teddycloud:

Tag What it is
latest, 0.7.0, 0.7, 0 the newest release (git tag tc_vX.Y.Z)
nightly-develop the current develop branch
rc, rc0.7.1, rc_v0.7.1 release candidates, see below

Before a release there can be release candidates (rc) for testing. They are cut from develop with a git tag rc_vX.Y.Z (more candidates of the same version: rc_vX.Y.Z-1, rc_vX.Y.Z-2, ...). rc always points to the newest candidate and rc0.7.1 to the newest candidate of version 0.7.1; the exact tag (e.g. rc0.7.1-1) stays available. A candidate is published as Docker image only (no GitHub release), never moves latest or the version tags, and the version shown by TeddyCloud is v0.7.1-rc, v0.7.1-rc1, ... Please test them and report problems before the release. How to cut one is described in CONTRIBUTING.md.

Development and bulding

Please use the develop for your development and pull requests. Stable builds are available from the master branch. Don't forget to clone the submodules with --recurse-submodules. To catch sanitizer in you IDE set a breakpoint on __asan::ReportGenericError.

Local Development Sandbox

dev-sandbox/ – Run TeddyCloud locally with mock data (tonies, Toniebox, TAF) to try out features and see changes during development. Builds and runs a local image.

Details: dev-sandbox/README.md.

Build and Run in Editor (VS Code)

  • Build once: Terminal (or F1) -> Run Task -> build (uses .vscode/tasks.json).
  • Debug/run: open Run and Debug, select [linux] teddyCloud, press F5 (uses .vscode/launch.json).
  • F5 runs the prelaunch build task automatically and starts bin/teddycloud with gdb.
  • For web UI in devcontainer, open http://localhost:<port>/web on your forwarded HTTP port (You can find the port in F1 -> 'Ports: Focus on Ports view).

Contribution Workflow (teddycloud + teddycloud_web)

TeddyCloud consists of two repositories: the backend (teddycloud) and the web frontend (teddycloud_web) as a submodule. Built web files live in contrib/data/www/.

Workflow for contributors:

  1. Backend-only changes: Open a PR against teddycloud – no submodule changes needed.
  2. Frontend-only changes: Open a PR against teddycloud_web – no PR against teddycloud needed.
  3. Changes in both repos: Create and merge both PRs separately (teddycloud_web first, then teddycloud). Do not commit submodule pointer changes in the teddycloud PR – a maintainer will handle that.

Build and publish workflows (GitHub Actions):

Workflow Trigger Description
Make web and commit Manual (workflow_dispatch) Builds the web from the teddycloud_web submodule, commits files to contrib/data/www/, pushes, and triggers the Docker build.
Docker Image Publish Matrix Push to master/develop or tags (tc_v... releases, rc_v... release candidates) Builds Docker images automatically.

After merging: Once both PRs are merged, a maintainer runs the "Make web and commit" workflow. It builds the frontend from the current teddycloud_web state (same branch), commits the built files, and updates the submodule pointer if needed. The subsequent push triggers the Docker build automatically.

Attribution

The icons used are from here:

Thanks for the original authors for these great icons.

Categories

Related apps

Explore more like this

Explore all

Links

Details

Repository
ghcr.io/toniebox-reverse-engineering/teddycloud:latest
Last Updated2026-11-16
First Seen2024-01-22

Runtime arguments

Web UI
http://[IP]:[PORT:80]
Network
bridge
Privileged
false

Template configuration

Web UI (HTTP)Porttcp

Port for the TeddyCloud web interface. Not used on a custom network, where the container's own IP serves port 80.

Target
80
Default
7780
Value
7780
Toniebox (HTTPS)Porttcp

Port the Toniebox connects to. It must stay 443. If 443 is already in use on Unraid, use a custom network with its own IP instead.

Target
443
Default
443
Value
443
Web UI (HTTPS)Porttcp

Optional HTTPS port for the web interface.

Target
8443
Default
8443
Value
8443
configPathrw

Server and Toniebox settings

Target
/teddycloud/config
Default
/mnt/user/appdata/teddycloud/config
Value
/mnt/user/appdata/teddycloud/config
certsPathrw

Server and Toniebox certificates. Place the certificates dumped from your Toniebox here.

Target
/teddycloud/certs
Default
/mnt/user/appdata/teddycloud/certs
Value
/mnt/user/appdata/teddycloud/certs
contentPathrw

Audio content served to the Toniebox (the box's virtual SD card)

Target
/teddycloud/data/content
Default
/mnt/user/appdata/teddycloud/data/content
Value
/mnt/user/appdata/teddycloud/data/content
libraryPathrw

Your audio library

Target
/teddycloud/data/library
Default
/mnt/user/appdata/teddycloud/data/library
Value
/mnt/user/appdata/teddycloud/data/library
firmwarePathrw

Firmware backups

Target
/teddycloud/data/firmware
Default
/mnt/user/appdata/teddycloud/data/firmware
Value
/mnt/user/appdata/teddycloud/data/firmware
cachePathrw

Image cache for content images

Target
/teddycloud/data/cache
Default
/mnt/user/appdata/teddycloud/data/cache
Value
/mnt/user/appdata/teddycloud/data/cache
custom_imgPathrw

Custom images for the custom tonies list

Target
/teddycloud/data/www/custom_img
Default
/mnt/user/appdata/teddycloud/data/www/custom_img
Value
/mnt/user/appdata/teddycloud/data/www/custom_img
pluginsPathrw

Web plugins for TeddyCloud

Target
/teddycloud/data/www/plugins
Default
/mnt/user/appdata/teddycloud/data/www/plugins
Value
/mnt/user/appdata/teddycloud/data/www/plugins
PUIDVariable

User ID the server runs as. TeddyCloud sets ownership of /teddycloud to this user and group on start.

Default
99
Value
99
PGIDVariable

Group ID the server runs as.

Default
100
Value
100