Getting Started

Getting Started

Goal: get from zero to a running bring-up loop (Mac browser voice or Pi terminal) without reading every contract first.

---

Choose your path

Path	When	Guide
Mac browser voice	No Pi yet; iterate on STT/TTS/kiosk	Dev Loop — Loop B+
Mac bridge + Pi peripherals	Real mic/camera, debugger on Mac	Dev Loop — Loop B
Full Pi production	Demo / soak	Installation · Runbook

---

Prerequisites checklist

AI server

• agentic-orchestration ≥ v1.27.0 (speech advertise needs ≥ v1.28)
• AGENTIC_SERVE_SESSION_OVERLAY=1 and AGENTIC_SERVE_MCP_TUNNEL=1
• CodeProject.AI on :32168 with Object Detection + Face Processing on CUDA
• Optional: speech sidecars on :8090 / :8091 with AGENTIC_SPEECH_ENABLED=1

Pi (production)

• Raspberry Pi OS 64-bit Bookworm
• Dart SDK ^3.5, Python 3.11+, Chromium
• Camera + mic + HDMI panel enumerated
• Ethernet preferred over Wi-Fi for frame/audio jitter

Mac (dev)

• Repo cloned, Dart + Python available
• Optional: config/comstar.mac.env from the example (gitignored)

Full environment facts: Baselines.

---

Fastest demo (Mac)

git clone https://github.com/zlatko-lakisic/comstar.git
cd comstar

cp config/comstar.mac.env.example config/comstar.mac.env
# edit camera/mic if needed
set -a && source config/comstar.mac.env && set +a

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

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

Inject a fake transcript (dev only):

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

(On LAN-bound admin, also send X-Comstar-Lan-Token / ?token=.)

---

First production steps on the Pi

1. Install bridge, audio, kiosk.
2. Copy config/comstar.example.yaml → config/comstar.yaml and set AO / CPAI URLs.
3. make deploy from the Mac (or see Runbook).
4. Enroll a face from the terminal camera.
5. Train or bypass wake word for bring-up.
6. Walk the attention ladder with doctor.

---

Read next

1. Architecture — where each process lives
2. Contracts — before changing any interface
3. Dev Loop — stop walking into frame
4. Contributing for Agents — if an AI agent is implementing