Configuration

Configuration

COMSTAR loads a single YAML file into a typed ComstarConfig at bridge start. Unknown keys are a fatal startup error — a typo'd threshold that silently uses a default is a debugging nightmare on a device with no keyboard.

Annotated template: config/comstar.example.yaml in the repo.

---

Example (comstar.yaml)

orchestration:
  base_url: http://10.0.10.16:8765
  token: ""                    # x-warpgate-token — never commit
  ttl_seconds: 3600
  timeout_seconds: 15
  overlay_root: ./overlays/comstar

vision:
  codeproject_url: http://10.0.10.16:32168
  detection_endpoint: /v1/vision/detection
  recognize_endpoint: /v1/vision/face/recognize
  ambient_fps: 1
  engaged_fps: 3
  person_confidence: 0.60
  face_confidence: 0.40
  recognize_votes: 2
  identity_ttl_seconds: 300

audio:
  wakeword_model: ./models/hey_comstar.onnx
  wakeword_threshold: 0.55
  vad_silence_ms: 700
  max_utterance_seconds: 15
  followup_window_seconds: 25
  duplex: half                 # half | full

avatar:
  render: local                # local | streamed
  model: ./assets/comstar.glb
  tts: piper
  piper_voice: en_US-ryan-high

attention:
  face_attention_trigger: true
  stranger_mode: restricted    # restricted | greet | ignore

dev:
  bind_lan: false              # production MUST stay false
  lan_token: ""

---

Validation rules (CONTRACTS §7)

Key	Rule
vision.ambient_fps	0.2 ≤ x ≤ 5
vision.engaged_fps	ambient_fps ≤ x ≤ 10
vision.person_confidence	0.3 ≤ x ≤ 0.95
vision.face_confidence	0.3 ≤ x ≤ 0.95
vision.recognize_votes	1 ≤ x ≤ 10
audio.wakeword_threshold	0.2 ≤ x ≤ 0.95
audio.vad_silence_ms	300 ≤ x ≤ 2000
audio.followup_window_seconds	0 ≤ x ≤ 30
orchestration.timeout_seconds	5 ≤ x ≤ 60
attention.stranger_mode	restricted | greet | ignore
avatar.render	local | streamed

---

Dev vs production configs

File	Purpose
comstar.yaml	Production on Pi — dev.bind_lan: false
comstar.dev.yaml	Dev mode only — may set bind_lan: true + lan_token
comstar.mac.env	Device env for Mac bring-up (gitignored)

LAN WebSocket binding requires all three gates: COMSTAR_ENV=dev, basename comstar.dev.yaml, non-empty dev.lan_token. See Security.

---

Overlay agents

File	Role
overlays/comstar/agent_providers/voice_responder.yaml	Conversational agent — spoken-output constraints (~40 words, no markdown/lists/URLs)
overlays/comstar/agent_providers/greeter.yaml	Engaged greeting — fast, small MCP set
overlays/comstar/mcp_providers/google_workspace.yaml	Session-overlay Google MCP definition

---

Related pages

• Environment Variables
• Contracts
• Installation
• Speech