---
title: Reachy Tales
emoji: 🏴‍☠️
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
hf_oauth: true
hf_oauth_expiration_minutes: 480
short_description: Voice-driven story adventures, narrated by your Reachy Mini.
tags:
  - reachy_mini
  - reachy_mini_js_app
---

# Reachy Tales

Voice-driven story adventures for Reachy Mini. The robot becomes the narrator and characters; the user replies in natural language; story state is driven by a clean, testable engine.

## Quick start

1. Open the Space, sign in with Hugging Face.
2. Paste an OpenAI API key with Realtime API access into the settings panel.
3. Pick your robot.
4. Tap the orb. The narrator greets you and offers stories.

## Architecture

- **`packages/story-engine/`** — pure TypeScript library: data loading, scene graph, storyline DAG, flag rules, prompt builder. No DOM / robot / LLM dependencies. Independently testable.
- **`src/`** — JS HF Space app. Wires the engine into the OpenAI Realtime API (via WebRTC over the robot peer) and into the Reachy Mini JS SDK. Body motion (idle breathing, listening cues, speech-driven head sway, dance/emotion library) is ported from the [reference conversation app](https://huggingface.co/spaces/tfrere/reachy-mini-minimal-js-conversation-app).
- **`content/`** — story data (English).

See [design spec](docs/superpowers/specs/2026-04-29-reachy-tales-design.md).

## Local dev

```bash
npm install
npm test --workspace story-engine
npm run dev   # http://localhost:5173
```

Local dev requires:
- A Reachy Mini accessible (Lite via USB or Wireless on network)
- An OpenAI API key with Realtime + chat-completions access
- A registered HF OAuth app for `localhost:5173` (see settings panel for the client-id field)

## Deployment

Push to the HF Space remote → auto-builds the Docker image and rolls out (~1-2 min).