Runbook

Runbook

Operational guide for the COMSTAR terminal (Phase 1).
Hardware baseline: Baselines. Dev workflow: Dev Loop.

---

Pi layout

Path	Purpose
/opt/comstar/src	Deployed git tree (rsync target)
/opt/comstar/src/config/comstar.yaml	Production config (not in git)
/opt/comstar/src/models/	Wake-word ONNX, avatar GLB
SSH	Host comstar (key auth) — see baselines for IP
Local STT/TTS	Optional fallback :8090 / :8091
~/.config/systemd/user/	comstar-bridge, comstar-audio, comstar-kiosk, comstar-stt, comstar-tts

make deploy
# or: bash deploy/deploy.sh

---

Boot sequence (splash → kiosk)

1. Plymouth — COMSTAR artwork during early boot. Once: sudo bash /opt/comstar/src/scripts/install-plymouth-comstar.sh
2. Blank session — LightDM autologin + labwc without panels. Once: bash /opt/comstar/src/scripts/install-pi-session.sh (and sudo-install the LightDM drop-in if prompted). From the Mac after deploy: make pi-session then make plymouth.
3. Chromium splash — comstar-kiosk opens branded splash with spinner (:8769), waits for bridge boot.txt, then loads the live kiosk.

Temporary desktop: systemctl --user stop comstar-kiosk, restore ~/.config/labwc/rc.xml.pre-comstar if present, re-login.

---

1. Enroll a face

→ Vision & Face Enrollment

./scripts/enroll_face.sh <userid>
curl -sS -X POST http://10.0.10.16:32168/v1/vision/face/list | jq .

---

2. Start the processes

Production (Pi)

systemctl --user enable --now comstar-bridge comstar-audio comstar-kiosk
systemctl --user status comstar-bridge comstar-audio comstar-kiosk

Prefer Reach speech when Ada advertises hello.speech. Local STT/TTS units are optional fallback.

Development (Mac — browser loop)

cp config/comstar.mac.env.example config/comstar.mac.env
set -a && source config/comstar.mac.env && set +a

make stt-dev
export COMSTAR_STT_URL=http://127.0.0.1:8090

COMSTAR_ENV=dev make bridge-dev
make kiosk-dev
# Chrome: http://127.0.0.1:5173/?bridge=ws://127.0.0.1:8777/kiosk

Notes:

• Kiosk has no camera preview — bridge owns the camera.
• Overlay paths are cwd-relative — start bridge from repo root or set absolute overlay_root.

Mac bridge + Pi audio

COMSTAR_ENV=dev make bridge-dev
make kiosk-dev
make audio-sync   # on Pi side of the loop

→ Dev Loop

---

3. Speech

→ Speech

Confirm bridge logs speech_reach vs speech_fallback.

---

4. Train wake word

→ Wake Word

---

5. Admin console and event injection

Full page: Admin Console.

Heal / liveness (no token):

curl -sS http://127.0.0.1:8781/admin/health
# alias: http://127.0.0.1:8781/health

Ops UI: make admin → http://127.0.0.1:8781/admin/ (needs LocalForward 8781). LAN: http://<pi-ip>:8781/admin/?token=<token>.

When COMSTAR_ENV=dev, inject via POST /admin/inject:

curl -sS -X POST http://127.0.0.1:8781/admin/inject \
  -H 'content-type: application/json' \
  -H 'X-Comstar-Lan-Token: <token>' \
  -d '{"event": "TranscriptReady", "text": "What time is it?"}'

Supported: PersonDetected, PersonAbsent, FaceRecognized, FaceUnknown, WakeWord, SpeechStart, SpeechEnd, TranscriptReady, ResponseReady, PlaybackEnded, Tick, AttentionError, VisionDegraded, VisionRecovered.

Injected events log src: injected.

---

6. Rollback

Symlinked releases (Dev Loop § Deploy layout):

ssh comstar 'ln -sfn /opt/comstar/releases/PREVIOUS /opt/comstar/current && \
  systemctl --user restart comstar-bridge comstar-audio comstar-kiosk'

Or redeploy a known-good commit: git checkout <sha> && make deploy.

---

7. Privacy kill switch

→ Privacy Model

systemctl --user stop comstar-bridge comstar-audio comstar-kiosk comstar-stt comstar-tts

---

8. Health checks

make doctor
make test
make logs

Service	Default	Check
Bridge WS (kiosk)	127.0.0.1:8777	kiosk connects, ready logged
Bridge WS (audio)	127.0.0.1:8778	audio connects
Admin + OAuth	127.0.0.1:8781	GET /admin/health; UI at /admin/; OAuth at /oauth/google/*
Dev inject	127.0.0.1:8781/admin/inject	COMSTAR_ENV=dev only
STT	Ada :8090 or local	/health; log speech_reach vs speech_fallback
TTS	Ada :8091 or local	/health or POST /v1/audio/speech
AO Reach	10.0.10.16:8765	spike/reach_hello.dart
CodeProject.AI	10.0.10.16:32168	scripts/verify_cpai.sh

---

9. Common failures

→ Troubleshooting

---

10. Google Workspace

→ Google Workspace

---

Related pages

• Admin Console
• Installation
• Configuration
• Dev Loop
• Baselines