Add HuggingFace Spaces live demo infrastructure

Docker-based demo that runs the full dashboard with reachy-mini-daemon
in simulation mode. Supervisor manages daemon + app lifecycle. Includes
graceful fallbacks for missing hardware (GStreamer, Bluetooth) so the
app runs cleanly in containers without audio/BT hardware.

New files: Dockerfile.demo, supervisord.demo.conf, demo-start.sh,
README.demo.md, .dockerignore

Modified: audio_output.py (GStreamer availability check),
bluetooth.py (bluetoothctl availability check),
index.html (Try Live Demo button)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,26 @@
+# Landing page assets (not needed in demo container)
+demo_video.mp4
+frames/
+screenshots/
+docs.html
+style.css
+README.md
+index.html
+README.demo.md
+
+# Git
+.git/
+.gitattributes
+.gitignore
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+
+# Media (runtime-generated, not needed in image)
+media/
+
+# Settings (runtime-generated on Reachy, not needed in image)
+settings.json

Dockerfile.demo

@@ -0,0 +1,48 @@
+# HuggingFace Spaces demo — runs the full dashboard with a simulated robot.
+#
+# Build:  docker build -f Dockerfile.demo -t hw-demo .
+# Run:    docker run -p 8042:8042 hw-demo
+# Browse: http://localhost:8042
+
+FROM python:3.12-slim
+
+# ── System dependencies ──────────────────────────────────────────
+# libosmesa6-dev  — headless OpenGL for MuJoCo (no GPU needed)
+# libgl1-mesa-glx — GL runtime (MuJoCo shared libs expect it)
+# tmux            — shell tab uses shared tmux sessions
+# curl            — startup script health checks
+# supervisor      — manages daemon + app lifecycle
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libosmesa6-dev \
+    libgl1-mesa-glx \
+    tmux \
+    curl \
+    supervisor \
+    && rm -rf /var/lib/apt/lists/*
+
+# MuJoCo headless rendering — OSMesa software renderer, no GPU required
+ENV MUJOCO_GL=osmesa
+
+# HuggingFace Spaces requires non-root user with uid 1000
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:${PATH}"
+
+WORKDIR /home/user/app
+
+# Install MuJoCo + reachy-mini SDK (provides reachy-mini-daemon command)
+RUN pip install --no-cache-dir --user mujoco "reachy-mini"
+
+# Copy the hello_world app and install as editable package
+# (editable so the daemon discovers it via entry points)
+COPY --chown=user:user . .
+RUN pip install --no-cache-dir --user -e .
+
+# Make startup script executable
+RUN chmod +x demo-start.sh
+
+# The app serves on port 8042 (HF proxy forwards to this)
+EXPOSE 8042
+
+# Supervisor manages: (1) daemon in sim mode, (2) startup script
+CMD ["supervisord", "-n", "-c", "/home/user/app/supervisord.demo.conf"]

README.demo.md

@@ -0,0 +1,36 @@
+---
+title: Hello World Demo
+emoji: 🤖
+colorFrom: purple
+colorTo: cyan
+sdk: docker
+app_port: 8042
+pinned: false
+---
+
+# Hello World Demo
+
+Live interactive demo of the **Hello World** dashboard running with a simulated Reachy Mini robot. No physical robot needed — the daemon runs in simulation mode with full MuJoCo kinematics.
+
+**[View documentation and source code on the main space](https://huggingface.co/spaces/panny247/hello_world)**
+
+## What works
+
+- 3D MuJoCo simulation with 20 scenes and 21 skins
+- Joystick head control (moves the simulated robot)
+- 81 emotions and 20 dances with 3D preview
+- 6 oscillation patterns (sway, nod, circle, breathe, figure-8, look around)
+- AI conversation (bring your own API key in Settings)
+- YOLO WebGPU vision (uses your browser camera)
+- System telemetry charts
+- Settings persistence
+- Scratchpad (generative UI)
+- Timers and alarms
+- Shell terminal
+
+## Hardware-only features (unavailable in demo)
+
+- Robot speaker and microphone (no USB audio hardware)
+- Bluetooth A2DP (no BlueZ stack)
+- AuraBox LED display (no peripheral)
+- Smart home integrations (no local network access)

demo-start.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# Startup script for HuggingFace Spaces demo.
+#
+# Waits for the daemon to be healthy, wakes it up (transitions from
+# not_initialized → ready), then starts the hello_world app.
+
+set -e
+
+DAEMON_URL="http://localhost:8000"
+APP_URL="http://localhost:8042"
+
+# ── Wait for daemon health endpoint ──────────────────────────────
+echo "[demo] Waiting for daemon to start..."
+for i in $(seq 1 60); do
+    if curl -sf "${DAEMON_URL}/api/daemon/status" > /dev/null 2>&1; then
+        echo "[demo] Daemon is up (took ${i}s)"
+        break
+    fi
+    if [ "$i" -eq 60 ]; then
+        echo "[demo] ERROR: Daemon did not start within 60s"
+        exit 1
+    fi
+    sleep 1
+done
+
+# ── Wake up the daemon (not_initialized → ready) ─────────────────
+echo "[demo] Waking up daemon..."
+curl -sf -X POST "${DAEMON_URL}/api/daemon/start?wake_up=true" || true
+sleep 3
+
+# ── Start the hello_world app ────────────────────────────────────
+echo "[demo] Starting Hello World app..."
+curl -sf -X POST "${DAEMON_URL}/api/apps/start-app/hello_world" || true
+
+# ── Wait for the app to be serving ────────────────────────────────
+echo "[demo] Waiting for app to respond..."
+for i in $(seq 1 30); do
+    if curl -sf "${APP_URL}/api/settings" > /dev/null 2>&1; then
+        echo "[demo] Hello World is live on port 8042"
+        break
+    fi
+    if [ "$i" -eq 30 ]; then
+        echo "[demo] WARNING: App did not respond within 30s (may still be starting)"
+    fi
+    sleep 1
+done
+
+echo "[demo] Startup complete."

hello_world/api/audio_output.py

@@ -36,11 +36,15 @@ __all__ = ['AudioRouter']
 import asyncio
 import logging
 import os
+import shutil
 import subprocess
 import tempfile
 
 import numpy as np
 
+# Check once at import time — avoids noisy error logs in containers without GStreamer
+_HAS_GSTREAMER = shutil.which("gst-launch-1.0") is not None
+
 logger = logging.getLogger("reachy_mini.app.hello_world.audio_output")
 
 # Bluetooth A2DP sample rate (full quality)
@@ -158,6 +162,9 @@ class AudioRouter:
         hardware with the daemon.  This is the same approach as the reference
         app and ensures the XMOS DSP sees the reference signal for AEC.
         """
+        if not _HAS_GSTREAMER:
+            logger.debug("GStreamer not available, skipping robot audio playback")
+            return
         cmd = [
             "gst-launch-1.0", "-q",
             "filesrc", f"location={filepath}", "!",

hello_world/api/bluetooth.py

@@ -22,6 +22,7 @@ import json
 import logging
 import math
 import re
+import shutil
 import subprocess
 import urllib.request
 
@@ -44,6 +45,8 @@ _UUID_CAPABILITIES = {
 
 def _run_bluetoothctl(args: list, timeout: int = 10) -> subprocess.CompletedProcess:
     """Run a bluetoothctl command with timeout."""
+    if not shutil.which("bluetoothctl"):
+        raise FileNotFoundError("bluetoothctl not found")
     return subprocess.run(
         ["bluetoothctl"] + args,
         capture_output=True, text=True, timeout=timeout

index.html

@@ -524,7 +524,10 @@
                 <div class="stat-label">Robot Skins</div>
             </div>
         </div>
-        <a href="docs.html" class="hero-btn">Read the Full Documentation <span class="arrow">&rarr;</span></a>
+        <div style="display: flex; gap: 1rem; justify-content: center; flex-wrap: wrap;">
+            <a href="https://huggingface.co/spaces/panny247/hello_world-demo" class="hero-btn" style="background: linear-gradient(135deg, rgba(124, 92, 252, 0.25), rgba(92, 224, 216, 0.15));">Try Live Demo <span class="arrow">&rarr;</span></a>
+            <a href="docs.html" class="hero-btn">Read the Full Documentation <span class="arrow">&rarr;</span></a>
+        </div>
     </div>
 </section>
 

supervisord.demo.conf

@@ -0,0 +1,31 @@
+; Supervisor config for HuggingFace Spaces demo.
+;
+; Manages two processes:
+;   1. reachy-mini-daemon --sim  — simulated robot server on port 8000
+;   2. demo-start.sh            — waits for daemon, wakes it, starts the app
+
+[supervisord]
+nodaemon=true
+logfile=/tmp/supervisord.log
+pidfile=/tmp/supervisord.pid
+childlogdir=/tmp
+
+[program:daemon]
+command=reachy-mini-daemon --sim
+autostart=true
+autorestart=true
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+
+[program:startup]
+command=/home/user/app/demo-start.sh
+autostart=true
+autorestart=false
+startsecs=0
+exitcodes=0
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0