Frequently Asked Questions (FAQ)

Quick answers covering installation, usage, models, networking, privacy, GPU, and ecosystem. Search by keyword.

---

1. Installation & Startup

Q1. Which platform should I install?

Windows 11/10 is the priority. Familiars is a Windows-first application with full feature support.

macOS has partial support but is incomplete:

Feature	macOS Status
Device fingerprint (src/base/auth/device.py)	macOS has a real implementation (Keychain); Windows uses hostname-only fingerprint
Auto-start (src/utils/autorun.py)	Has a macOS branch (launchd)
Daily tools (src/utils/daily_tools.py)	macOS uses AppKit / Quartz conditional imports
WeChat listener (wcferry)	Windows only (wcferry only provides a Win32 FWWeChat backend)
UI automation (uiautomation)	Windows only (UIA accessibility bridge)
Audio control (pycaw)	Windows only

Q2. What do I do if pip install -r requirements.txt fails?

Common errors and solutions:

Error	Cause	Fix
Could not find torch==2.9.0+cu126	Missing PyTorch index URL	pip install -r requirements.txt --index-url https://download.pytorch.org/whl/cu126
AttributeError: _ARRAY_API not found	onnxruntime version too old (<1.28) incompatible with NumPy 2.x	Ensure onnxruntime==1.28.0 (already corrected in requirements.txt)
lunardate not found	Lunar calendar library not installed	pip install lunardate==0.3.0
pydantic_settings not found	Not installed	pip install pydantic-settings>=2.5.0
python-dotenv not found	Not installed	pip install python-dotenv>=1.0.0
uiautomation install fails (macOS)	No wheel available for macOS	requirements.txt already constrains this to sys_platform == "win32" — macOS should not attempt to install it
Build fails (hnswlib / insightface)	Missing VC++ build tools	Install Visual C++ Redistributable 2015–2022 or Build Tools
Downloads very slow	PyPI mirror slow	Use a local mirror: -i https://pypi.tuna.tsinghua.edu.cn/simple (keep the PyTorch index URL unchanged)

Q3. I can't connect to the bridge / it keeps spinning after startup?

Troubleshoot in this order:

1. Check the port file: Look at workspace/.bridge.port. If port 18711 is already occupied, the bridge automatically selects a free port and writes it to this file. The CLI reads it automatically.

2. Check .env: Are BASE_URL / API_KEY / DEFAULT_MODEL filled in? If startup reports Missing required environment variable(s), you've missed a required field.

3. Check bridge logs: Look at workspace/.bridge.log and search for ERROR / CRITICAL.

4. Check GPU detection: Look at workspace/gpu_tier.json and confirm the GPU tier was detected correctly.

5. Try the HTTP fallback: Set FAMILIARS_HTTP_INSECURE=1 and the bridge falls back to HTTP + uvicorn (bypassing HTTPS/2 + hypercorn).

6. Check for dual instances: Does workspace/.bridges.json contain multiple instances? Electron has a single-instance lock (app.requestSingleInstanceLock()); a second launch should automatically focus the existing window. If there are zombie processes, kill them manually and restart.

7. Check proxies: If the system has a dead proxy configured (e.g. v2ray/SS not started), httpx will report ConnectError [WinError 10061]. _inject_no_proxy() in config.py automatically adds the *_BASE_URL hosts to NO_PROXY, but you can also check manually.

Q4. Why can't I use uvicorn src.bridge.app:app --reload?

Three fatal problems:

1. Loses HTTP/2: uvicorn does not support HTTP/2. Familiars relies on hypercorn's HTTP/2 multiplexing to bypass Chromium's 6-socket-per-host HTTP/1.1 limit (the old uvicorn path stalled the renderer during rapid agent switching).

2. CUDA race condition: --reload initializes CUDA on a worker thread. Windows WDDM cannot tolerate the first CUDA touch coming from a non-main thread and crashes outright (0xC0000005).

3. Pre-warm is lost: app.py's on_event("startup") executes a precise startup order (CUDA pin → broker bootstrap → pool watchdog → browser hooks → prewarm → autorun → rehydrate). Reload re-runs these initializations, causing state confusion.

Correct entry point: python -m src.bridge.run (hypercorn + HTTPS/2 + self-signed certificate).

Q5. What if port 18711 is occupied?

The bridge's port resolution priority:

1. Probe whether 18711 is free: isPortFree(18711) check
2. Free → use 18711 (default)
3. Occupied → pickFreePort() requests a free port from the OS
4. Write the port to workspace/.bridge.port + workspace/.bridges.json
5. The CLI automatically reads .bridge.port (or .bridges.json + psutil PID liveness check)

Common occupancy scenarios:

• The previous bridge did not exit cleanly and the port was not released
• Another program is using 18711
• Two Electron instances competing

Solutions:

• Wait 30 seconds for the OS to reclaim the port
• Manually kill the occupying process (netstat -ano | findstr :18711)
• Or just use a dynamic port (the CLI adapts automatically)

Q6. What if two bridge instances conflict?

Familiars has multiple layers of protection:

1. Electron single-instance lock: app.requestSingleInstanceLock(); a second launch triggers the second-instance event, the first instance focuses its window automatically, and the second immediately calls app.quit().

2. Bridge port health check: _port_healthy() detects whether the port is already occupied before binding.

3. _inspectExistingBridge(): Before Electron gloms onto an existing bridge, it cross-checks PID liveness + window responsiveness + age. A zombie bridge (anyio thread pool deadlocked but hypercorn TLS still answering /health) is killed + respawned.

4. app.py exempts registered siblings: when the bridge starts it detects whether an instance with the same token is already running.

If you still have a conflict:

# View current bridge instances
cat workspace/.bridges.json

# Manually kill the zombie process
taskkill /PID <pid> /F

# Clean up port files
del workspace/.bridge.port
del workspace/.bridges.json

# Restart
python -m src.bridge.run

Q7. Is the first startup being slow (1-2 minutes) normal?

Yes, it is normal. The pre-warm sequence at bridge startup:

1. CUDA pin (main thread, ~50ms)
2. Broker workshop bootstrap
3. AnyIO thread limiter bump
4. Pool saturation watchdog
5. Browser lifecycle hooks
6. Embedder pre-warm (bge-m3, ~400MB download on first run)
7. rembg pre-warm (background removal model)
8. rewriter pre-warm (query rewriting model)
9. Most-recent agent's digital human model pre-warm (GPT-SoVITS)
10. Autorun install/drift check
11. Monitor rehydrate
12. Cron job rehydrate
13. Skill scheduler rehydrate

The slowest part of the first startup is the embedder download. Subsequent startups use the workspace/gpu_tier.json cache and skip the nvidia-smi probe.

---

2. Usage

Q8. The conversation has no memory?

Troubleshooting steps:

1. Check whether the embedder is downloaded: the first startup needs to download bge-m3 (~400MB). Look at workspace/.bridge.log and search for bge-m3.

2. Check EMBEDDING_MODEL: is it configured correctly in .env (default BAAI/bge-m3)?

3. Check whether the conversation expired: DIALOGUE_EXPIRE_TIME defaults to 3600 seconds (1 hour). Memory for expired conversations is released.

4. Check the RAG parameters:

   • RAG_DENSE_TOPK (default 20) — dense recall candidate count
   • RAG_RERANK_MIN_SCORE (default 0.0) — rerank minimum score threshold
   • RAG_CHUNK_SIZE (default 800) — chunk size

5. Memory must be written first: RAG hits need "something previously written/said" — first have the agent read something ("read USER.md"), then ask "I remember…"

6. Check the GPU tier: under mode0 (no GPU), the memorizer uses a cloud LLM 2-call hack, which may be slower or less stable.

Q9. Tools always require approval?

That is the default privacy-protection behavior. The approval threshold is controlled by security_level:

Level	Behavior
high	All tools require approval
medium (default)	Medium- and high-risk tools require approval
low	Only high-risk tools require approval

Temporarily disable (dev/internal environments only):

FAMILIARS_APPROVAL_DISABLED=1 python -m src.bridge.run

Permanent adjustment: set security_level=low in .env, or adjust it in SettingsCenter → Privacy tab.

Q10. Every reply is very long / I can't see tool calls?

Possible causes:

1. The model does not support tool calling: DEFAULT_MODEL must be an agentic model (supports function calling / tool use). Switch to gpt-4o / claude-3 / qwen-max, etc.

2. MAX_TURNS is too large: default 50 turns. If the model keeps looping in tool calls, you can lower it (e.g. MAX_TURNS=20).

3. intense_mode is on: default True, the agent keeps executing until "definitive success". If you don't need that, set intense_mode=False in .env.

4. turbo_mode conflict: turbo_mode and intense_mode are mutually exclusive. turbo_mode=True skips approval but keeps plan verification.

5. Turn budget escalation: MAX_TURNS is no longer a hard cap — when exhausted, ConversationSession asks _turn_budget_escalator (manager LLM) whether to extend. If you don't want extension, lower MAX_TURNS.

Q11. The digital human doesn't speak?

The digital human needs:

1. Local GPU: at least tier4 (4GB+ VRAM)
2. GPT-SoVITS model: the speech synthesis model must be downloaded to the workspace/ directory in advance
3. need_figure=True: AssistantConfig.need_figure defaults to True in .env
4. need_audio=True: AssistantConfig.need_audio defaults to True in .env

Without a GPU (mode0), the digital human panel shows a robot mascot emoji instead of an animated avatar.

See the digital human chapter.

Q12. Voice input doesn't work?

Voice input depends on:

1. faster-whisper: the ASR engine (already in requirements.txt)
2. Microphone permission: Windows Settings → Privacy → Microphone → allow desktop apps to access
3. @ricky0123/vad-web: voice activity detection (VAD), runs in the browser

Debugging:

• Check the browser console for microphone permission errors
• Check whether the faster-whisper model has been downloaded
• Try manual push-to-talk (hold to speak, release to recognize)

Q13. I closed the window and can't find it again?

After closing the window, Electron hides to the system tray (does not exit):

1. Find the tray icon: Windows system tray in the bottom-right (you may need to click ^ to expand hidden icons)
2. Right-click → "Restore window"
3. Or left-click the tray icon

First-hide hint: the first time you close the window a system notification appears guiding you to restore from the tray. Marker file: %APPDATA%/familiars/.tray-hint-shown.

Exit completely: right-click the tray → "Exit background (fully quit)".

---

3. Model Configuration

Q14. Can I use a private/self-hosted embedding?

Yes. EMBEDDING_MODEL / RERANKER_MODEL support:

• HuggingFace model name: BAAI/bge-m3 (default)
• Local path: /path/to/local/model
• OpenAI-compatible endpoint: configured uniformly through BASE_URL

You need to restart the bridge after modifying .env.

Q15. How are the local small models (decider / rewriter / memorizer) trained?

They are managed by the training pipeline under training/ in the repo; daily usage doesn't need to care:

• rewriter: query rewriting (prompt defined by workspace/rewriter/prompt.md)
• decider: proactive decision-making (src/base/gpu_tier.py controls the loading strategy)
• memorizer: memory writing (QLoRA fine-tuning)

These models load automatically at bridge startup (when the GPU tier allows); no manual training is needed.

See Architecture · Proactive Decision Decider.

Q16. What's the difference between MANAGER_MODEL and DEFAULT_MODEL?

Variable	Purpose	Recommendation
DEFAULT_MODEL	Default conversation model for all agents	Cost-effective model (e.g. gpt-4o-mini / qwen-plus)
MANAGER_MODEL	Reserved for the manager (agent 0/1)	Stronger model (e.g. gpt-4o / claude-3-opus)
MINI_MODEL	Local lightweight model	Default Qwen2.5-1.5B (decider, etc.)
FAST_MODEL	Low-latency fast model	Empty (falls back to DEFAULT_MODEL)

The manager handles executive summaries, persona evolution, framework doc indexing, and cross-agent routing, which need stronger reasoning.

Q17. When is FAST_MODEL used?

FAST_MODEL is used for latency-sensitive scenarios:

• Draft parsing (DraftConfirmModal)
• Fast classification
• Lightweight query rewriting

When empty it falls back to DEFAULT_MODEL. If your DEFAULT_MODEL is slow (e.g. gpt-4o), you can set FAST_MODEL=gpt-4o-mini to speed up lightweight tasks.

---

4. Networking & Connectivity

Q18. ConnectError [WinError 10061] connection refused?

Common causes:

1. System proxy issue: a dead proxy is configured (v2ray/SS not running). _inject_no_proxy() in config.py automatically adds the *_BASE_URL hosts to NO_PROXY, but you can also check manually.

2. Bridge not started: check workspace/.bridge.port and confirm the bridge process is alive.

3. Port mismatch: the CLI's --base-url does not match the bridge's actual port.

4. TLS certificate not trusted: the self-signed certificate workspace/.bridge.crt is not trusted. The CLI pins this certificate automatically; the browser needs to trust it once manually.

Q19. HTTP/2 vs HTTP fallback?

Familiars uses HTTPS + HTTP/2 (hypercorn) by default:

• Advantage: HTTP/2 multiplexing bypasses Chromium's 6-socket-per-host limit (no renderer blocking when rapidly switching agents)
• Certificate: self-signed workspace/.bridge.crt, trusted automatically by Electron
• CLI: pins the certificate automatically (session.verify = str(crt))

Falling back to HTTP (not recommended unless hypercorn or certificate trust is broken):

FAMILIARS_HTTP_INSECURE=1 python -m src.bridge.run

After the fallback it uses uvicorn + HTTP/1.1. Electron's main.js and the CLI both read FAMILIARS_HTTP_INSECURE to stay protocol-aligned.

Q20. The CLI reports 401 Unauthorized?

X-Bridge-Token is missing or wrong.

Troubleshooting:

1. Check whether workspace/.bridge_token exists
2. Check whether the bridge has started (the token is generated at bridge startup)
3. Specify the token manually: python main.py --token <token> agents list
4. Or set the environment variable: BRIDGE_TOKEN=<token>

Q21. SSE streaming responses get interrupted?

Possible causes:

1. Network timeout: TIMEOUT defaults to 300 seconds. Long tasks may time out.
2. Proxy disconnects: the system proxy or firewall cuts off long-lived connections.
3. Bridge restart: all SSE streams are dropped when the bridge restarts.
4. Chromium socket limit: the 6-socket limit under HTTP/1.1. Using HTTP/2 avoids this.

---

5. Privacy & Security

Q22. Are my conversations uploaded?

By default all memory/conversations/databases are local:

• SQLite database: workspace/familiars.db
• Dialogue trees: workspace/agents/agent_<id>/dialogue_<n>/
• Memory: workspace/agents/agent_<id>/ + workspace/USER.md
• Sensitive information: workspace/SECRET.json (encrypted storage)
• Bridge: 127.0.0.1:18711 (local access only)

Requests that leave the network:

• LLM inference (the endpoint configured by BASE_URL)
• Embedding model download (HuggingFace, first run)
• Search tools (ddgs / tavily)
• Marketplace index (FAMILIARS_MARKETPLACE_URL)
• OTA update check (UPDATE_URL)

See the security model.

Q23. The approval card shows "sensitive information"?

sensitive_detector does three-level sanitization:

1. gitleaks: regex matching for key/token/password patterns
2. Presidio: NER to identify personal information (name/email/phone/address)
3. mini-LLM: a lightweight model judges contextual sensitivity

Matched sensitive content is stored only as ciphertext in SECRET.json (crypto.encrypt_value, HKDF info = b"familiars-secrets-v1").

This is a feature, not a bug — it prevents sensitive information from being stored in plaintext in conversation records.

Q24. Can the HKDF info string be changed?

The HKDF info in src/base/crypto.py is b"familiars-secrets-v1".

⚠️ Changing it invalidates every secret already written to SECRET.json, because the info must match at decryption time. If you must change it, you need to implement a re-encryption migration at the same time (decrypt old → encrypt with new info → write back).

---

6. GPU & Performance

Q25. What if GPU tier detection is inaccurate?

Force override:

# Force a specific tier
FAMILIARS_GPU_TIER=tier6 python -m src.bridge.run

# Force re-detection (ignore cache)
FAMILIARS_GPU_TIER_FORCE_REDETECT=1 python -m src.bridge.run

Adjust thresholds:

# Adjust the tier4 upper bound (MiB)
FAMILIARS_TIER4_MAX_MB=6000

# Adjust the tier6 upper bound (MiB)
FAMILIARS_TIER6_MAX_MB=8000

Cache location: workspace/gpu_tier.json (you can delete it manually and restart).

Runtime downgrade: the VRAM pressure watchdog can downgrade the tier at runtime (set_transient_tier), effective in memory without writing to disk. It clears automatically after recovery (clear_transient_tier).

Q26. Not enough VRAM (OOM)?

1. Downgrade the GPU tier: FAMILIARS_GPU_TIER=tier4 (or tier6)
2. Turn off unneeded features:
   • need_figure=False — disable the digital human
   • need_video=False — disable video processing
   • DAILY_MONITOR_DISABLED=True — disable daily monitoring
3. Reduce concurrent models: under tier4 models load sequentially (rewriter is evicted before reranker loads)
4. Use API-only mode: FAMILIARS_GPU_TIER=mode0 (all local models fall back to cloud)

Q27. How is Apple Silicon (MPS) support?

Apple Silicon has no nvidia-smi and resolves to mode0 (API-only) by default.

Force-enable local inference (experimental):

FAMILIARS_GPU_TIER=tier4 python -m src.bridge.run

The MPS backend is exposed through the +cpu wheel of the PyTorch CPU index (MPS is in the same build). But performance and stability are not as good as NVIDIA CUDA, and some operations (e.g. insightface) may not support MPS.

Recommendation: Apple Silicon users should use API-only mode and rely on cloud models.

---

7. Ecosystem (Broker / Recipe / Flow)

Q28. What are Broker / Recipe / Flow?

Concept	Description	Tutorial
Recipe	Automation "recipe" for a single skill (graph: input → process → output)	Recipe tutorial
Flow	Multi-agent multi-stage workflow (with parallel/branch/sub-track)	Flow tutorial
Broker	Shareable application package (manifest+UI+plugin), installable from the marketplace	Broker tutorial

Q29. Are Brokers in the marketplace safe?

Marketplace submissions require:

• Ed25519 signature (author key: ~/.familiars/authors/<name>.key)
• sha256 verification (file tree hash)
• Review on publish (manual queue)

⚠️ Brokers currently still run inside the bridge process (no sandbox), so only installing work from trusted authors is recommended.

Install command:

python main.py broker install --file my_broker.broker.zip
# or from a URL
python main.py broker install --url https://example.com/my_broker.broker.zip

See the Broker tutorial and the security model.

Q30. Can I migrate my agent data to another machine?

Yes. Just copy the entire workspace/ directory.

Automatic path-drift alignment: src.base.paths_align.align_all_paths() runs automatically at bridge startup (src/bridge/app.py, after the CUDA pin and before route imports):

1. Repo-root drift: compares every dialogue.path prefix with _repo_root(). After moving the repo, the next boot transparently rewrites every dialogue.json + turn_*/plan.json + step_*.json.
2. External-directory aliases: for renames outside the repo (e.g. the data folder), run python -m src.tools.paths_migrate <old> <new> --record once and every future boot replays it.

Detected path pairs are appended to workspace/.paths_aliases.json (for auditing).

The auto-alignment is idempotent (0-hit files are skipped), so it costs nothing on stable boots.

Log files (.bridge.log, audit.log) are never touched — they are the authentic historical record.

---

8. Development & Debugging

Q31. How do I view bridge logs?

Log files:

File	Content
workspace/.bridge.log	Main bridge log (INFO/WARNING/ERROR)
workspace/audit.log	Audit log (tool calls, approvals, sensitive-information detection)
workspace/.bridge.watchdog.log	Watchdog log
workspace/memorizer_audit.jsonl	Memory audit (JSONL)
workspace/reminders/*.jsonl	Reminder logs
workspace/agents/agent_<id>/daily_*.jsonl	Per-agent daily logs

Manager tools: the Manager (agent 0) has list_logs / read_log tools and can browse logs directly in the conversation.

View via CLI:

# Tail in real time
tail -f workspace/.bridge.log

# Search for errors
grep ERROR workspace/.bridge.log

Q32. How do I debug the frontend?

1. DevTools: open with Ctrl+Shift+I or F12
2. Vite HMR: npm run electron:dev supports hot module replacement; editing Vue components refreshes automatically
3. Vue DevTools: install the browser extension
4. Network panel: check the status of /api/* requests
5. Console: search for [error] / [warn]

Q33. How do I debug the backend?

1. Log level: set LOG_LEVEL=DEBUG (or INFO / WARNING / ERROR)
2. Breakpoint debugging: python -m debugpy --listen 5678 -m src.bridge.run
3. Tests:

   # Run all tests
   pytest
   
   # Run a specific test
   pytest test/bridge/test_app.py -v
   
   # Run recipe tests
   pytest test/recipes/ -v

4. In-memory tests: use FAMILIARS_DB_PATH=:memory: to avoid disk side effects

Q34. How do I add a new bridge route?

1. Create a new file under src/bridge/routes/ (e.g. my_route.py)
2. Define router = APIRouter(prefix="/api/my-route", tags=["my-route"])
3. Import and mount it in src/bridge/app.py
4. Update src/models/RAG/bridge_api_surface.py (the manager API surface index)
5. If CLI support is needed, add a command group in main.py

Q35. How do I add a new tool?

1. Implement the tool class under src/tools/ or src/utils/
2. Register an instance in src/tools/tool_dispatcher.py
3. Update workspace/tools.json (schema)
4. If it needs to be visible to a specific client, update src/models/clients/*_client.py

---

9. Other

Q36. How do I update Familiars?

Source installation:

git pull
pip install -r requirements.txt --index-url https://download.pytorch.org/whl/cu126
cd electron && npm install

One-click install:

• electron-updater checks for updates automatically (UPDATE_URL configures the feed URL)
• Check interval: UPDATE_CHECK_INTERVAL_HOURS (default 24 hours)
• Manual check: Settings Center → About → Check for updates

Q37. Where is the database structure?

SQLite database: workspace/familiars.db (src/storage/db.py:get_default_db_path)

Override path: FAMILIARS_DB_PATH (tests can use :memory:)

Migrations: v1 … v19 under src/storage/migrations/ (including .sql and .py variants). v16 is a Python migration (v16__schedule_dedup_and_unique.py). v18 (broker) and v19 (broker_workshop) are the broker layer.

Q38. What's the priority for the config file (.env)?

load_dotenv(override=True) in src/base/config.py makes the .env file override existing environment variables.

Priority (high to low):

1. .env file (override=True)
2. Process environment variables (export FOO=bar)
3. Default values (Field(default=...))

This means if the shell exported an old value, the new value in .env will override it.

Q39. What is WORKSPACE_ROUTE?

WORKSPACE_ROUTE is the parent directory of the workspace/ directory (usually the repository root).

• Default: "" (empty → falls back to cwd)
• Electron: automatically set to the repository root
• Bridge: WORKSPACE_ROUTE is pinned at import time in src/bridge/app.py

Do not set WORKSPACE_ROUTE to workspace/ itself — it is the parent directory of workspace/.

Q40. Didn't find an answer?

• See the User Manual
• See the Architecture documentation
• See the CLI reference
• Go to the feedback page to submit a question or join the community