| name | familiar-check-env |
| description | Validate the .env configuration for familiar-ai. Detects common misconfigurations like wrong ports, missing MODEL, or TOOLS_MODE issues that cause silent failures or timeouts. |
familiar-check-env
Validate the .env (or environment) for familiar-ai and surface likely misconfigurations before they cause cryptic errors.
When to Use
- "It's not responding" / "Request timed out" with a local LLM
- Setting up familiar-ai for the first time
- Switching between platforms (Anthropic → LM Studio → Ollama, etc.)
- After upgrading familiar-ai when new env vars were added
What to Check
Read the current .env (or os.environ) and validate each section:
Section 1: Core LLM
| Var | Expected | Common Mistake |
|---|
PLATFORM | anthropic / openai / gemini / kimi | Typo, or not set (defaults to anthropic) |
API_KEY | Non-empty | Forgotten, wrong key for the platform |
MODEL | Platform-appropriate model ID | Not set → defaults to claude-haiku-4-5-20251001 or gpt-4o-mini, which LM Studio won't serve |
BASE_URL | Valid URL | Wrong port (LM Studio=1234, Ollama=11434), HTTP vs HTTPS |
TOOLS_MODE | prompt for local models, native for real OpenAI | Missing → now defaults to prompt for non-OpenAI (was native before v0.x) |
Platform-specific checks:
PLATFORM=anthropic → API_KEY should start with sk-ant-; BASE_URL and TOOLS_MODE are ignoredPLATFORM=openai + BASE_URL not set → falls back to https://api.openai.com/v1 (real OpenAI)PLATFORM=openai + BASE_URL set to local → warn if TOOLS_MODE=native (may cause timeout on models that don't support function calling)PLATFORM=gemini → API_KEY should be a Google AI Studio key; BASE_URL is ignoredPLATFORM=kimi → API_KEY is a Moonshot AI key
LM Studio specific:
- Default port is 1234, not 11434
- LM Studio only binds to
localhost by default; cross-machine access requires enabling "Allow connections from network" in LM Studio settings
MODEL must exactly match the identifier shown in LM Studio's loaded model list
Ollama specific:
- Default port is 11434
- Ollama binds to
0.0.0.0 by default, so cross-machine access usually works without extra config
Section 2: Camera (optional)
| Var | Notes |
|---|
CAMERA_HOST | IP of the camera on the local network |
CAMERA_USERNAME | Usually admin |
CAMERA_PASSWORD | Required if CAMERA_HOST is set |
CAMERA_ONVIF_PORT | Default 2020 for Tapo; check your camera's spec |
Warn if CAMERA_HOST is set but CAMERA_PASSWORD is empty — camera tool will silently skip init.
Section 3: TTS / Voice (optional)
| Var | Notes |
|---|
ELEVENLABS_API_KEY | Required for TTS |
ELEVENLABS_VOICE_ID | Defaults to a built-in voice; override for custom voices |
GO2RTC_URL | Default http://localhost:1984; only needed for camera speaker |
GO2RTC_STREAM | Default tapo_cam |
Check that mpv or ffplay is available in PATH for local speaker playback:
which mpv || which ffplay
Section 4: Mobility / Robot Vacuum (optional)
| Var | Notes |
|---|
TUYA_API_KEY | From Tuya IoT Platform |
TUYA_API_SECRET | From Tuya IoT Platform |
TUYA_DEVICE_ID | The vacuum's device ID in Tuya |
TUYA_REGION | us / eu / cn / in |
Mobility tool silently skips init if any of these are missing.
Output Format
Report findings grouped by severity:
[PLATFORM: openai]
✅ API_KEY is set
✅ BASE_URL = http://192.168.10.6:1234/v1 (LM Studio)
⚠️ TOOLS_MODE not set → defaulting to "prompt" (correct for local models)
❌ MODEL not set → will request "gpt-4o-mini" which LM Studio may not serve
Fix: set MODEL=<your-loaded-model-identifier>
[CAMERA]
✅ CAMERA_HOST = 192.168.10.5
❌ CAMERA_PASSWORD is empty → camera tool will not initialize
[TTS]
⚠️ ELEVENLABS_API_KEY not set → TTS disabled
⚠️ mpv not found in PATH, ffplay not found → no local audio playback
[MOBILITY]
ℹ️ TUYA_* not set → mobility disabled (OK if no robot vacuum)
Always end with a summary:
Summary: 1 error, 2 warnings. Fix errors before starting the agent.
