docs(demo): add DEMO-RUNBOOK.md; ElevenLabs key sourced from Infisical
Full demo-day runbook — secrets, pre-flight (recover.sh + voice proxy), the three acts (web/Telegram/voice), mid-demo recovery, and gotchas. ELEVENLABS_API_KEY now lives in Infisical on icarus (project cloud-providers, env prod, alongside the other provider keys); runbook pulls it via the macbook-admin machine identity. Cloud token and node token stay manual env exports for now. Co-Authored-By: Claude Opus 4.8 <[email protected]>
This commit is contained in:
Omar Sobh
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
413230255e
commit
eb8c41b14b
@@ -0,0 +1,96 @@
|
|||||||
|
# APESS Demo Runbook — Multi-Channel Agent Controls the LED Matrix
|
||||||
|
|
||||||
|
One on-board agent on the Arduino Uno Q changes the physical **13×8 LED-matrix
|
||||||
|
animation** on command from **web chat, Telegram, and voice** — same agent, same
|
||||||
|
`matrix_pattern` tool, all on cloud sonnet via the reliable `/webhook` path.
|
||||||
|
|
||||||
|
## Secrets
|
||||||
|
|
||||||
|
Three env-only secrets are needed. **ElevenLabs lives in Infisical** on the `icarus`
|
||||||
|
instance (project `cloud-providers`, env `prod`, alongside the other provider API keys):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
DOM=http://icarus.lan:8443 # or https://icarus.taila4f562.ts.net
|
||||||
|
export INFISICAL_TOKEN=$(infisical login --method=universal-auth \
|
||||||
|
--client-id=$(cat ~/.infisical/macbook-admin-id) \
|
||||||
|
--client-secret=$(cat ~/.infisical/macbook-admin-secret) \
|
||||||
|
--domain=$DOM --silent --plain)
|
||||||
|
export ELEVENLABS_API_KEY=$(infisical secrets get ELEVENLABS_API_KEY \
|
||||||
|
--projectId=0788e188-b746-4ea0-a4b2-e0c2d0aec1b6 --env=prod --domain=$DOM --plain)
|
||||||
|
```
|
||||||
|
|
||||||
|
The other two are **exported manually** (not yet in Infisical — see "next steps" if you
|
||||||
|
want them vaulted too):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export ANTHROPIC_OAUTH_TOKEN=sk-ant-oat01-… # Claude Max setup-token (cloud brain)
|
||||||
|
export NODE_TOKEN=zc_… # Uno Q gateway bearer token
|
||||||
|
```
|
||||||
|
|
||||||
|
**None of these may be written to disk or committed** — env-only. Infisical is the vault;
|
||||||
|
`recover.sh` and `serve.py` read them from the environment.
|
||||||
|
|
||||||
|
## Pre-flight (~5 min before, board plugged into USB)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ~/projects/apress
|
||||||
|
# (secrets exported per above)
|
||||||
|
./deploy/uno-q/recover.sh # brings up node + verifies sonnet + matrix (all-green)
|
||||||
|
|
||||||
|
# voice proxy — leave running in its own terminal:
|
||||||
|
NODE_URL=http://127.0.0.1:8080 NODE_TOKEN=$NODE_TOKEN ELEVENLABS_API_KEY=$ELEVENLABS_API_KEY \
|
||||||
|
python3 deploy/voice-client/serve.py 8090
|
||||||
|
```
|
||||||
|
|
||||||
|
`recover.sh` re-tunnels (`adb forward :8080`), relaunches the daemon with the cloud
|
||||||
|
token in its environment, starts the matrix bridge app, and confirms
|
||||||
|
`agent=demo` is on `claude-sonnet-5` and `matrix_pattern` fires.
|
||||||
|
|
||||||
|
**On the workshop LAN:** point `NODE_URL` at the board's LAN IP (`http://192.168.x.x:8080`)
|
||||||
|
instead of the adb-forwarded `127.0.0.1:8080`, so the browser voice client reaches the
|
||||||
|
board over the network.
|
||||||
|
|
||||||
|
## The three acts
|
||||||
|
|
||||||
|
1. **Web chat** — prompt *"show the rain animation"* → matrix changes + live activity feed.
|
||||||
|
2. **Telegram** — **t.me/Apess2026Bot** → *"change it to a beating heart"* → the *same
|
||||||
|
physical matrix* changes, driven from a phone. (One-time pairing: `/bind <code>` — the
|
||||||
|
code prints in the daemon log at startup; grep `bind code`.)
|
||||||
|
3. **Voice** — **http://localhost:8090** in Chrome → hold-to-talk *"make it wave"* → matrix
|
||||||
|
changes and the reply is **spoken back in the ElevenLabs voice** (Sarah).
|
||||||
|
|
||||||
|
Patterns the agent understands: `off, rain, heart, wave, sparkle, checker, solid, blink`.
|
||||||
|
|
||||||
|
## If the board disconnects mid-demo
|
||||||
|
|
||||||
|
The recurring USB drop kills the daemon/llama/bridge and loses the env-only cloud token.
|
||||||
|
Re-plug, then:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./deploy/uno-q/recover.sh # ~30s, re-injects the token, verifies end-to-end
|
||||||
|
```
|
||||||
|
|
||||||
|
The voice proxy auto-recovers via the re-armed tunnel (no restart needed). If it was
|
||||||
|
stopped, relaunch the `serve.py` line above.
|
||||||
|
|
||||||
|
## Gotchas / facts
|
||||||
|
|
||||||
|
- **Cloud token is env-only** — a disconnect loses it; recovery *must* re-export it (the
|
||||||
|
script uses `$ANTHROPIC_OAUTH_TOKEN` from your shell).
|
||||||
|
- **Use `/webhook`, not `/ws/chat`** — the WS path builds a fresh agent that omits the
|
||||||
|
peripheral `matrix_pattern` tool; the voice client's `serve.py` proxies `/webhook` for
|
||||||
|
this reason.
|
||||||
|
- **First turn after a fresh daemon** is a touch slower (cold); the pre-flight
|
||||||
|
`recover.sh` call warms it.
|
||||||
|
- **ElevenLabs free tier** can only use the premade voices attached to the account (not
|
||||||
|
"library" voices → 402). Default `EXAVITQu4vr4xnSDxMaL` (Sarah) works.
|
||||||
|
- **Board serial** `65301572`. **Bridge app**: `~/ArduinoApps/uno-q-bridge`
|
||||||
|
(`arduino-app-cli`, needs `TMPDIR=/tmp`).
|
||||||
|
|
||||||
|
## Where things live
|
||||||
|
|
||||||
|
- `deploy/uno-q/recover.sh` — one-command node recovery.
|
||||||
|
- `deploy/voice-client/` — browser voice client + `serve.py` proxy (STT/TTS + ElevenLabs).
|
||||||
|
- zeroclaw fork (`fix/uno-q-flash-timeouts`) — resident matrix responder + `matrix_pattern`
|
||||||
|
tool + Telegram channel.
|
||||||
|
</content>
|
||||||
Reference in New Issue
Block a user