Installation Guide

This page covers three installation paths: Windows from source (developer / recommended), Windows one-click installer (end users), and Docker Relay (for deploying the broker relay only). Familiars is a Windows-first application; this guide focuses on Windows. macOS support is limited — see the macOS section at the end.

1. Prerequisites

Dependency	Minimum Version	Notes
Python	3.10+	Backend bridge and all AI models run in this process
Node.js	18+	Electron frontend rendering + Vite dev server
npm	9+	Comes with Node.js
Git	Any	Clone the repository
CUDA Toolkit	12.6 (recommended)	Required for local GPU inference; API-only mode (mode0) works without GPU
NVIDIA Driver	≥535	Pairs with CUDA 12.6; check with `nvidia-smi`
Visual C++ Redistributable	2015–2022	Required by some Python packages (`hnswlib`, `insightface`)

GPU Tiers

On startup, the bridge reads GPU VRAM via nvidia-smi and assigns one of four tiers (source: src/base/gpu_tier.py):

Tier	VRAM Threshold	Behavior
`mode0`	No discrete GPU / <1 GB	API-only: all local models fall back to cloud LLM; no decider, no local rewriter
`tier4`	1–5 GB (default `FAMILIARS_TIER4_MAX_MB=5000`)	4-bit quantized + sequential model loading (rewriter evicted before reranker loads); decider/memorizer queued
`tier6`	5–7.5 GB (default `FAMILIARS_TIER6_MAX_MB=7500`)	rewriter+embedder+reranker co-loaded; voice calls (audio-only) allowed; decider/memorizer bf16
`tier8`	≥7.5 GB	Full: all models loaded simultaneously at highest precision

Cache file: workspace/gpu_tier.json. Override via environment variables:

FAMILIARS_GPU_TIER=tier6 — Manually pin a tier (for testing lower-tier fallback on a high-end GPU)
FAMILIARS_TIER4_MAX_MB=5000 — Adjust tier4 upper bound (MiB)
FAMILIARS_TIER6_MAX_MB=7500 — Adjust tier6 upper bound (MiB)
FAMILIARS_GPU_TIER_FORCE_REDETECT=1 — Force re-detection, ignore cache

Apple Silicon has no nvidia-smi and defaults to mode0 (API-only). To force local inference, set FAMILIARS_GPU_TIER=tier4 (MPS backend), but performance and stability are not guaranteed.

2. From Source (Recommended)

2.1 Clone the Repository

bash

git clone <repo-url> familiars
cd familiars

2.2 Python Virtual Environment

bash

# Create virtual environment
python -m venv .venv

# Activate (PowerShell)
.venv\Scripts\Activate.ps1

# Activate (CMD)
.venv\Scripts\activate.bat

# Activate (Git Bash / WSL)
source .venv/bin/activate

2.3 Install Python Dependencies

Critical: PyTorch must be installed from the official index with CUDA 12.6 support. Otherwise pip install torch pulls the CPU-only wheel from PyPI, making local QLoRA inference 10× slower.

bash

# Windows (CUDA 12.6)
pip install -r requirements.txt --index-url https://download.pytorch.org/whl/cu126

# macOS (CPU / MPS)
pip install -r requirements.txt --index-url https://download.pytorch.org/whl/cpu

Slow network? Add a mirror: -i https://pypi.tuna.tsinghua.edu.cn/simple (PyTorch index URL stays the same; the mirror only accelerates PyPI-side packages).

Key Dependencies in requirements.txt

Package	Version	Purpose
`torch`	2.9.0+cu126	PyTorch core (CUDA 12.6)
`torchvision`	0.24.0+cu126	Vision models
`torchaudio`	2.9.0+cu126	Audio processing
`transformers`	4.57.3	HuggingFace model loading
`sentence_transformers`	5.2.2	Embedding models
`FlagEmbedding`	1.4.0	RAG reranking
`fastapi`	0.136.1	HTTP API framework
`hypercorn[h2]`	≥0.16.0	HTTP/2 server
`onnxruntime`	1.28.0	ONNX inference (background removal, etc.)
`openai`	2.36.0	LLM API client
`httpx`	0.28.1	Async HTTP client
`apscheduler`	3.11.2	Scheduled task dispatch
`faster-whisper`	≥1.0.0	Speech recognition (ASR)
`playwright`	1.59.0	Browser automation
`pydantic-settings`	≥2.5.0	Environment variable validation
`python-dotenv`	≥1.0.0	`.env` loading
`cryptography`	45.0.5	Sensitive data encryption
`paddleocr`	3.5.0	OCR text recognition
`insightface`	0.7.3	Face detection (digital human)
`mediapipe`	0.10.35	Face / gesture tracking

Platform-locked packages (handled automatically by requirements.txt):

Windows only: uiautomation, wcferry (WeChat RPC), pycaw, comtypes, wmi, pywin32
macOS only: AppKit, Quartz (pyobjc)

2.4 Install Playwright Browsers

bash

playwright install chromium

2.5 Configure `.env`

Copy .env.example to .env (or create it at the repo root) and fill in the required fields:

Required Environment Variables

Variable	Type	Description	Example
`BASE_URL`	string	OpenAI-compatible API endpoint	`https://api.familiars.cn/v1`
`API_KEY`	string	LLM provider API key	`sk-xxxxx`
`DEFAULT_MODEL`	string	Default dialogue model name	`gpt-4o`

MANAGER_MODEL defaults to gpt-4o, used by the manager (agent 0) for executive summaries and persona evolution. Typically a stronger model.

Optional Model Configuration

Variable	Default	Description
`MANAGER_MODEL`	`gpt-4o`	Manager-specific model
`MINI_MODEL`	`Qwen2.5-1.5B`	Local lightweight model (decider, etc.)
`FAST_MODEL`	empty (falls back to `DEFAULT_MODEL`)	Low-latency cloud fast model (draft parsing, quick classification)
`EMBEDDING_MODEL`	`BAAI/bge-m3`	Embedding model (sentence-transformers name or HuggingFace path)
`RERANKER_MODEL`	`BAAI/bge-reranker-v2-m3`	Reranker model

Runtime Tuning

Variable	Default	Description
`MAX_TURNS`	`50`	Maximum tool-call turns per conversation
`TIMEOUT`	`300`	HTTP request timeout (seconds)
`DIALOGUE_EXPIRE_TIME`	`3600`	Idle dialogue expiry time (seconds)
`SLIDE_WINDOW_SIZE`	`5`	Sliding window context size
`TOP_K`	`5`	RAG retrieval result count

FAMILIARS_* Environment Variables

Variable	Default	Description
`FAMILIARS_TIER4_MAX_MB`	`5000`	GPU tier4 VRAM upper bound (MiB)
`FAMILIARS_TIER6_MAX_MB`	`7500`	GPU tier6 VRAM upper bound (MiB)
`FAMILIARS_GPU_TIER`	auto-detected	Force a GPU tier (`mode0`/`tier4`/`tier6`/`tier8`)
`FAMILIARS_GPU_TIER_FORCE_REDETECT`	`0`	Set `1` to force GPU re-detection
`FAMILIARS_APPROVAL_DISABLED`	`0`	Set `1` to disable all tool approvals (use with caution, dev only)
`FAMILIARS_DB_PATH`	`workspace/familiars.db`	SQLite database path (use `:memory:` for tests)
`FAMILIARS_HTTP_INSECURE`	`0`	Set `1` to fall back to HTTP + uvicorn (no HTTPS/2 + hypercorn)
`FAMILIARS_BROKER_ADVERTISE_URL`	empty	Broker federation public/LAN base URL
`FAMILIARS_BROKER_BIND`	`127.0.0.1`	Bridge HTTP bind address (`0.0.0.0` exposes to other machines)
`FAMILIARS_FRAMEWORK_DOCS_TOPK`	—	Framework docs RAG retrieval count

RAG Tuning

Variable	Default	Description
`RAG_DENSE_TOPK`	`20`	Dense recall candidate count
`RAG_CHUNK_SIZE`	`800`	Chunk target size (characters)
`RAG_RERANK_MIN_SCORE`	`0.0`	Rerank minimum score threshold (0 = keep all)
`RAG_RRF_K`	`60`	Reciprocal Rank Fusion constant
`RAG_MULTIQUERY_N`	`1`	Local rewriter query variant count (1 = single query)

Circuit Breaker

Variable	Default	Description
`CB_FAILURE_THRESHOLD`	`5`	Failures before tripping the breaker
`CB_RECOVERY_SECONDS`	`30.0`	Recovery attempt interval (seconds)
`LLM_MAX_RETRIES`	`3`	Maximum retries per LLM call
`LLM_GATE_DISABLED`	`false`	Set `true` to disable concurrency gating (unlimited)

Third-Party Services (Optional)

Variable	Description
`HUGGING_FACE_API_KEY`	HuggingFace API key
`UPDATE_URL`	OTA update feed base URL (empty = disabled)
`UPDATE_CHECK_INTERVAL_HOURS`	Update check interval (default 24 hours)

2.6 Electron Frontend

bash

cd electron
npm install

Key frontend dependencies (electron/package.json):

Package	Version	Purpose
`vue`	^3.5.41	Frontend framework
`electron`	^30.0.0	Desktop shell
`pinia`	^2.1.7	State management
`@vue-flow/core`	^1.48.2	Graph visualization (recipe/flow editor)
`axios`	^1.7.0	HTTP client
`markdown-it`	^14.3.0	Markdown rendering
`highlight.js`	^11.11.1	Code highlighting
`mermaid`	^11.16.0	Flowchart rendering
`katex`	^0.17.0	Math formula rendering
`onnxruntime-web`	^1.26.0	Browser-side ONNX inference
`@ricky0123/vad-web`	^0.0.30	Voice Activity Detection (VAD)
`electron-updater`	^6.8.9	OTA auto-updates

3. Launch

Option A: Electron Full-Stack Dev Mode (Recommended)

bash

cd electron
npm run electron:dev

This will:

Start the Vite dev server (http://localhost:5173)
Wait for Vite to be ready, then open the Electron window
Electron auto-spawns the Python bridge subprocess (.venv/Scripts/python -m src.bridge.run)
Bridge serves at: https://127.0.0.1:18711 (hypercorn + HTTP/2 + self-signed cert auto-generated at workspace/.bridge.crt)

Option B: Bridge Only (Backend Tests / No GUI)

bash

.venv/Scripts/python -m src.bridge.run

⚠️ Do NOT use uvicorn src.bridge.app:app --reload — it drops HTTP/2 support, and the reload mechanism race-initializes CUDA on a worker thread, which crashes on Windows WDDM.

Option C: CLI-Driven (Requires Running Bridge)

bash

python main.py agents list --pretty
python main.py chat stream --prompt "Hello" --agent-id 1
python main.py todos create --title "Buy milk" --deadline 2026-07-05T18:00

CLI authentication uses the X-Bridge-Token header, auto-read from workspace/.bridge_token. Override with --token or the BRIDGE_TOKEN environment variable.

4. Windows One-Click Installer (End Users)

How the installer is built (developer perspective):

Enter electron/ and run npm run electron:build (Vite bundles the renderer + electron-builder produces a Windows NSIS installer).
The installer bundles Python-side dependencies into extraResources; first launch auto-generates workspace/ and .env.
User double-clicks to install → first launch prompts for LLM API endpoint (BASE_URL / API_KEY / model name).

Installer configuration (electron/package.json → build.nsis):

oneClick: false — Not one-click; allows directory selection
createDesktopShortcut: true — Creates desktop shortcut
createStartMenuShortcut: true — Creates Start Menu shortcut
Update feed: https://api.familiars.cn/_app-updates/ (electron-updater generic provider)

5. Docker Relay (Broker/Relay Deployment Only)

To self-host the Broker relay:

bash

cd deploy/relay/app
cp .env.example .env   # Fill in DOMAIN / CLOUDFLARE_API_TOKEN etc.
docker compose up -d

Architecture chain: Cloudflare → Caddy:443 (DNS-01 TLS) → relay:18712.

See deploy/relay/app/README.md for details.

6. macOS Notes

This repository is Python + Electron Windows-first. Some files have macOS branches but with lagging functionality:

File	macOS Status
`src/models/assistant.py`	Has macOS branch
`src/utils/autorun.py`	Has macOS branch (launchd)
`src/base/auth/device.py`	macOS has real implementation (Keychain); Windows has hostname-only fingerprint
`src/utils/daily_tools.py`	macOS imports `AppKit`/`Quartz` (conditional import)

For macOS, install PyTorch with the CPU index:

bash

pip install -r requirements.txt --index-url https://download.pytorch.org/whl/cpu

7. Common Installation Errors & Solutions

Problem	Cause / Fix
`pip install` reports `Could not find a version that satisfies the requirement torch==2.9.0+cu126`	Missing `--index-url https://download.pytorch.org/whl/cu126`; PyPI doesn't have `+cu126` suffix wheels
`AttributeError: _ARRAY_API not found`	`onnxruntime` too old (<1.28), incompatible with NumPy 2.x; ensure `onnxruntime==1.28.0` in requirements.txt
`pip install` is very slow	Add a mirror: `-i https://pypi.tuna.tsinghua.edu.cn/simple` (PyTorch index URL stays the same)
Startup complains about untrusted self-signed cert	Electron auto-trusts `workspace/.bridge.crt`; for CLI / browser, trust it once manually
Port 18711 is occupied	Bridge auto-calls `pickFreePort()` for a new port and writes it to `workspace/.bridge.port`; CLI reads that file automatically
`ModuleNotFoundError: No module named 'pydantic_settings'`	`pydantic-settings>=2.5.0` not installed; same for `python-dotenv>=1.0.0`
`nvcc not found` / CUDA compilation fails	Install CUDA Toolkit 12.6 + matching NVIDIA driver; or use pre-built wheels
`uiautomation` install fails (macOS)	requirements.txt already locks it with `sys_platform == "win32"`; macOS should not attempt to install it
First launch is very slow (1-2 min)	Normal — the bridge needs to prewarm embedder (`bge-m3`), rewriter, rembg, etc.; first launch also downloads them
Dual bridge instance conflict	Electron has a single-instance lock (`app.requestSingleInstanceLock()`); a second launch auto-focuses the existing window instead of starting a new instance
`torch` is using CPU version	Check `pip show torch` — the Version field should contain `+cu126`; otherwise reinstall
`lunardate` not found	Lunar date conversion library, included in requirements.txt; if missing, `pip install lunardate==0.3.0`

8. File Structure After First Launch

After first launch, the workspace/ directory is auto-generated:

workspace/
├── .bridge_token          # Bridge auth token (CLI reads automatically)
├── .bridge.port           # Bridge actual port (non-default when 18711 is occupied)
├── .bridge.crt            # Self-signed HTTPS certificate
├── .bridge.key            # Self-signed HTTPS private key
├── .bridge.log            # Bridge runtime log
├── .bridges.json          # Bridge instance info (PID + port)
├── familiars.db           # SQLite main database
├── gpu_tier.json          # GPU tier cache
├── SECRET.json            # Encrypted sensitive data (tokens, etc.)
├── .paths_aliases.json    # Path migration alias records
├── AGENTS.md              # Project-level agent rules
├── USER.md                # User profile (rolled up by memory writer)
├── IDENTITY.md            # Identity definition
├── agents/
│   └── agent_<id>/        # Each agent's dedicated directory
│       ├── dialogue_<n>/  # Dialogue tree data
│       └── reports/       # Daily / weekly / monthly / annual reports
├── manager/
│   ├── entries/           # Desktop shell icon assets
│   └── flows/             # Installed flow templates
└── rewriter/
    └── prompt.md          # Query rewriting prompt

Next: Quick Start →

Installation Guide ​

1. Prerequisites ​

GPU Tiers ​

2. From Source (Recommended) ​

2.1 Clone the Repository ​

2.2 Python Virtual Environment ​

2.3 Install Python Dependencies ​

Key Dependencies in requirements.txt ​

2.4 Install Playwright Browsers ​

2.5 Configure .env ​

Required Environment Variables ​

Optional Model Configuration ​

Runtime Tuning ​

FAMILIARS_* Environment Variables ​

RAG Tuning ​

Circuit Breaker ​

Third-Party Services (Optional) ​

2.6 Electron Frontend ​

3. Launch ​

Option A: Electron Full-Stack Dev Mode (Recommended) ​

Option B: Bridge Only (Backend Tests / No GUI) ​

Option C: CLI-Driven (Requires Running Bridge) ​

4. Windows One-Click Installer (End Users) ​

5. Docker Relay (Broker/Relay Deployment Only) ​

6. macOS Notes ​

7. Common Installation Errors & Solutions ​

8. File Structure After First Launch ​

Installation Guide

1. Prerequisites

GPU Tiers

2. From Source (Recommended)

2.1 Clone the Repository

2.2 Python Virtual Environment

2.3 Install Python Dependencies

Key Dependencies in requirements.txt

2.4 Install Playwright Browsers

2.5 Configure `.env`

Required Environment Variables

Optional Model Configuration

Runtime Tuning

FAMILIARS_* Environment Variables

RAG Tuning

Circuit Breaker

Third-Party Services (Optional)

2.6 Electron Frontend

3. Launch

Option A: Electron Full-Stack Dev Mode (Recommended)

Option B: Bridge Only (Backend Tests / No GUI)

Option C: CLI-Driven (Requires Running Bridge)

4. Windows One-Click Installer (End Users)

5. Docker Relay (Broker/Relay Deployment Only)

6. macOS Notes

7. Common Installation Errors & Solutions

8. File Structure After First Launch