Familiar

Self-hosted AI agent with Signal-grade encryption

Version Python License

Quick Start

Install from PyPI

pip install familiar-agent[llm]
export ANTHROPIC_API_KEY="sk-ant-..."   # or OPENAI_API_KEY
python -m familiar

Run from source

git clone https://github.com/omegcrash/familiar.git
cd familiar
pip install -e ".[llm]"
python -m familiar

If you have Ollama installed, it uses local AI (free, private). If you set an API key, it uses Claude or GPT instead.

That's it. No Docker, no databases, no config files needed.

Setup Wizard

For a guided setup experience, use the onboarding wizard:

python -m familiar --onboard          # CLI wizard (step-by-step)
python -m familiar --onboard-tui      # Rich terminal UI (keyboard-navigable)
python -m familiar --reconfigure      # Re-run setup to change settings

The wizard auto-detects your LLM providers (Anthropic, OpenAI, Gemini, Ollama), lets you configure channels (Telegram, Discord, Matrix, WhatsApp, Signal, iMessage, Teams, CLI), sets up encryption, and sends a test message — all in under 5 minutes. A web-based version is also available at /onboard on the dashboard.

See docs/CHANNELS.md for per-channel setup instructions.

To run the web wizard from another device on your LAN (e.g. setting up a Raspberry Pi from your laptop):

FAMILIAR_ONBOARD_LAN=1 python -m familiar --dashboard
# Then open http://<pi-ip>:5000/onboard from your laptop

What Is Familiar?

A self-hosted AI agent that runs on your machine — from a Raspberry Pi to a workstation. Talk to it through CLI, Telegram, Discord, Matrix, Teams, or the web dashboard. It remembers context, executes tools, manages your calendar, reads your email, controls GPIO pins, and browses the web.

Everything is encrypted locally. Your conversations never leave your hardware unless you choose a cloud LLM provider.

Features

Multi-provider LLM — Claude, GPT, Gemini, or local models via Ollama (llama3.2, deepseek-r1, qwen2.5, qwen3, mistral, gemma3, phi4)
60+ skills — email, calendar, browser, knowledge base, tasks, GPIO, voice, documents, Nextcloud, Gitea, Jellyfin, bookkeeping, and more
Signal-grade encryption — Double Ratchet secure transport, sessions and memory encrypted at rest
Multi-channel — CLI, Telegram, Discord, Matrix, Teams, web dashboard, Signal, iMessage, WhatsApp, SMS
Web dashboard — Svelte 5 + Tailwind UI with real-time activity monitoring, Memory Tree visualization, credential management, workspace panels per job class
9 job classes — Helper, Social Worker, Business Buddy, Nonprofit Director, Chef, Artist, Security Analyst, OSINT Researcher, Network Admin
Raspberry Pi optimized — runs on 4GB Pi with local Ollama models
Multi-device mesh — encrypted peer-to-peer networking, shared memories, model sharing, ICQ-style messaging
Memory Tree — unified FTS5 search + typed graph edges + PageRank ranking, 4-tier architecture with temporal validity
HIPAA-ready — compliance mode with audit logging, PHI detection, encryption at rest
Self-hosted services — provision Gitea, Mealie, Nextcloud, Jellyfin, SearXNG, Pi-hole via Podman/Docker
Circuit breaker resilience — automatic provider fallback, agent lifecycle events, tool category metrics
Self-hosted email server — built-in SMTP/IMAP server for fully self-hosted email

Advanced Installation

For running as a system daemon, Pi optimization, or full dependency install:

# Full install with all extras
pip install familiar-agent[full]

# Pi-specific with Ollama optimization
./familiar/scripts/install-pi.sh --with-ollama

# Nonprofit preset (email, calendar, tasks)
./familiar/scripts/install-pi.sh --nonprofit

See docs/INSTALL.md for detailed options.

Configuration

Copy and edit the sample config:

cp config.sample.yaml ~/.familiar/config.yaml

Key settings:

llm:
  default_provider: anthropic     # or openai, ollama
  anthropic_model: claude-sonnet-4-6
  ollama_model: llama3.2

agent:
  name: Familiar
  memory_enabled: true
  skills_enabled: true

security:
  encrypt_sessions: true
  encrypt_memory: true

Project Structure

familiar/
├── pyproject.toml           # Package config (pip install -e .)
├── Dockerfile               # Container build
├── config.sample.yaml       # Example configuration
├── familiar/
│   ├── __main__.py          # CLI entry point
│   ├── core/                # Agent, providers, memory, mesh, resilience
│   ├── channels/            # CLI, Telegram, Discord, Matrix, Teams, etc.
│   ├── skills/              # 60+ built-in skills
│   ├── dashboard/           # Flask backend + Svelte 5 frontend
│   │   ├── app.py           # API endpoints
│   │   ├── templates/       # v1 Jinja templates
│   │   └── frontend/        # v2 Svelte 5 + Tailwind (at /v2)
│   ├── services/            # Self-hosted service provisioning (Podman/Docker)
│   ├── onboard/             # Setup wizard
│   ├── docs/                # Documentation
│   └── tests/               # 103 test files

License

See LICENSE for full text.

Metadata

Release files for familiar-agent 1.16.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for familiar-agent 1.16.1
File	Size	Uploaded
familiar_agent-1.16.1.tar.gz	3.2 MB	Mar 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for familiar-agent 1.16.1
File	Interpreter	ABI	Platform	Reset
familiar_agent-1.16.1-py3-none-any.whl 3.6 MB Mar 25, 2026	Python 3	none	any	Details

Total release size: 6.8 MB

Release files / familiar_agent-1.16.1.tar.gz

Download URL	familiar_agent-1.16.1.tar.gz
Size	3.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`b2f42842f29ec0e7b7b51eb5352c4d32e8c1358e5d0a03254723d2038ed3dad0`
BLAKE2b-256 checksum How to use checksums	`68398ff1de8fe23a4633b1bb5185a7a8dd866410a9bae3e8bc64b97001090dd8`
Upload date	Mar 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`

Release files / familiar_agent-1.16.1-py3-none-any.whl

Download URL	familiar_agent-1.16.1-py3-none-any.whl
Size	3.6 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`230bdc66a7388d4be0d41444b2d75a3d30173f3e583a531afd26406172b2f5c3`
BLAKE2b-256 checksum How to use checksums	`6e38867c0a13f22b60085e09e415c1cb80c0831b47113817e95deea5240f97e5`
Upload date	Mar 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`