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.
orchestration:
base_url: https://10.0.10.16:8765 # https required when mtls.enabled
token: "" # optional x-warpgate-token (non-mTLS hosts)
ttl_seconds: 3600
timeout_seconds: 15
overlay_root: ./overlays/comstar
mtls:
enabled: true
# material_dir: ~/.local/share/comstar/ao-mtls
client_name: comstar-ai # CN on enroll; default hostname
trust_enrollment_ca: true # TOFU on first pair
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: ""
# Optional admin console (:8781/admin). Prefer COMSTAR_ADMIN_* env on the Pi.
# admin:
# bind_lan: false
# token: ""| 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 |
orchestration.mtls.enabled |
when true, base_url must be https://…
|
orchestration.mtls.material_dir |
optional; default ~/.local/share/comstar/ao-mtls
|
orchestration.mtls.client_name |
optional CN for enroll (default hostname) |
orchestration.mtls.trust_enrollment_ca |
default true (TOFU on first enroll) |
attention.stranger_mode |
restricted | greet | ignore
|
avatar.render |
local | streamed
|
| 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.
Admin HTTP (:8781) binds LAN independently via COMSTAR_ADMIN_BIND_LAN +
COMSTAR_ADMIN_TOKEN (or admin:). See Admin Console.
AO mTLS: enroll from Admin AO pairing or make ao-mtls-enroll TOKEN=….
Never commit PEMs under ao-mtls/. See ADR 0013.
Offline SoftAP when no uplink: disable with COMSTAR_HOTSPOT=0
(ADR 0014).
| 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 |