familiar-agent 1.4.1

Self-Hosted AI Companion Platform

🤝 Familiar

Self-hosted AI agent with Signal-grade encryption

---

Quick Start

Unzip, then run the script for your OS:

Linux / macOS / Raspberry Pi

cd familiar
./run.sh

Windows

Double-click run.bat, or from Command Prompt:

cd familiar
run.bat

Familiar auto-detects your setup. If you have Ollama installed, it uses local AI (free, private). If you set an API key, it uses Claude or GPT instead:

export ANTHROPIC_API_KEY="sk-ant-..."   # Claude
# or
export OPENAI_API_KEY="sk-..."          # GPT
./run.sh

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

---

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, 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, or local models via Ollama
• 36 skills — email, calendar, browser, knowledge base, tasks, GPIO, voice, and more
• Signal-grade encryption — sessions, memory, and data encrypted at rest
• Multi-channel — CLI, Telegram, Discord, web dashboard, SMS, Signal
• Raspberry Pi optimized — runs on 4GB Pi with local Ollama models
• Multi-device mesh — connect multiple Familiar instances across devices
• HIPAA-ready — compliance mode with audit logging and PHI detection

---

GUI Launcher

For a graphical interface (recommended on desktop):

python3 FamiliarLauncher.py

This opens a window for managing Ollama models, starting/stopping the agent, and viewing logs. Requires tkinter (sudo apt install python3-tk on Linux).

---

Advanced Installation

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

# Full install with venv + systemd service (Linux)
./scripts/install.sh

# Pi-specific with swap, GPU memory, and Ollama optimization
./scripts/install-pi.sh --with-ollama

# Windows full install with venv
scripts\install.bat

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-20250514
  ollama_model: llama3.2

agent:
  name: Familiar
  memory_enabled: true
  skills_enabled: true

security:
  encrypt_sessions: true
  encrypt_memory: true

---

Project Structure

familiar/
├── run.sh / run.bat         # Start here
├── FamiliarLauncher.py       # GUI launcher
├── __main__.py              # CLI entry point
├── core/                    # Agent, providers, memory, tools
├── channels/                # CLI, Telegram, Discord, etc.
├── skills/                  # 21 built-in skills
├── launcher/                # GUI + hardware detection
├── dashboard/               # Web dashboard
├── admin/                   # Admin panel
├── pwa/                     # Progressive web app
├── docs/                    # Documentation
└── scripts/                 # Install scripts + dev tools

---

License

MIT — Copyright (c) 2026 George Scott Foley

See LICENSE for full text.