Skip to main content

Familiar

Self-hosted AI agent with Signal-grade encryption

Version Python License


Quick Start

Install from PyPI

pip install "familiar-agent[llm,web,encryption]"
export ANTHROPIC_API_KEY="sk-ant-..."   # or OPENAI_API_KEY
python -m familiar          # web dashboard; the first run opens the setup wizard
python -m familiar --cli    # or chat in the terminal

Run from source

git clone https://github.com/omegcrash/familiar.git
cd familiar
pip install -e ".[llm,web,encryption]"
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

The setup wizard writes ~/.familiar/config.yaml for you. To start from the sample instead:

cp familiar/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

MIT — Copyright (c) 2026 George Scott Foley

See LICENSE for full text.

Metadata

Release files for familiar-agent 1.18.0

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.18.0
File Size Uploaded Provenance Actions
familiar_agent-1.18.0.tar.gz 3.2 MB Without provenance Details for familiar_agent-1.18.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for familiar-agent 1.18.0
File Interpreter ABI Platform Actions
familiar_agent-1.18.0-py3-none-any.whl Python 3 none any Details for familiar_agent-1.18.0-py3-none-any.whl

Total release size: 6.8 MB

Release files / familiar_agent-1.18.0.tar.gz

Download URL familiar_agent-1.18.0.tar.gz
Size 3.2 MB
Tags Source
SHA-256 checksum
How to use checksums
4dba716f2636081ea1bb25711b05ce0482dcdb35c3b7a1e8ddf59105c7a06aa6
BLAKE2b-256 checksum
How to use checksums
03f0a78b87f5dc844750d26440e5ffa14cb187b3afdb0c23265703c98b24629c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

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

Download URL familiar_agent-1.18.0-py3-none-any.whl
Size 3.7 MB
Tags Python 3
SHA-256 checksum
How to use checksums
dca849a7aeeb6d4389b4cf0e234d4b0ad4f7a2521132d2b6b6cb9c20ff979105
BLAKE2b-256 checksum
How to use checksums
1c30832e20a7c01ade9229c936c5d5c8928d4bf91b025a88752c8124eeca37ab
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for familiar-agent 1.18.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.18.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page