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

---

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. Dev event injection

When COMSTAR_ENV=dev, bridge serves POST http://127.0.0.1:8779/inject:

{"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
Dev inject	127.0.0.1:8779	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

• Installation
• Configuration
• Dev Loop
• Baselines