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. comstar-labwc session — LightDM autologin into labwc without --merge-config (no pcmanfm / wf-panel). Dark swaybg, then Chromium. Once: bash /opt/comstar/src/scripts/install-pi-session.sh or make pi-session.
3. Chromium splash — :8769 spinner → live kiosk when bridge is ready.

Restore Pi desktop for debugging:

sudo cp /etc/lightdm/lightdm.conf.pre-comstar /etc/lightdm/lightdm.conf
sudo systemctl restart lightdm

---

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.

---

5b. AO mTLS pairing

Ada serves HTTPS + client certs on :8765. After deploy:

1. Mint a one-time enroll token on Ada.
2. Admin → Ops → AO pairing, or headless:

make ao-mtls-enroll TOKEN=<one-time>   # on the Pi / via SSH

3. Confirm orchestration.base_url: https://10.0.10.16:8765 and orchestration.mtls.enabled: true.
4. Restart bridge; sessions should log mTLS on open.

Material: ~/.local/share/comstar/ao-mtls/ — never commit. Server cert must include an IP SAN when connecting by address. Details: ADR 0013, Admin Console.

---

5c. Offline SoftAP

If the Pi has no ethernet and no Wi‑Fi client, SoftAP COMSTAR-<hostname> comes up at 10.87.65.1. Join that SSID, then open Admin via the kiosk QR (or http://10.87.65.1:8781/admin/?token=…). Disable: COMSTAR_HOTSPOT=0. ADR 0014.

---

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	https://10.0.10.16:8765	mTLS enrolled; Admin AO pairing probe / GET /admin/api/ao_mtls
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