🛡️ FamClaw

A secure, local-first family AI gateway. Runs on Raspberry Pi, Mac, or any Linux box.

FamClaw is a lightweight Go gateway that connects your family to any AI model — local or cloud — through Telegram, WhatsApp, Discord, and a web interface. Every message goes through a policy engine before the AI ever sees it.

---

What it is

• A gateway, not an AI. FamClaw routes messages between your family and whatever LLM you configure — Ollama on your home server, OpenAI, Anthropic, OpenRouter, or any OpenAI-compatible endpoint.
• A policy enforcer. Every message is evaluated by OPA (Open Policy Agent) before reaching the LLM. Kids get age-appropriate responses. Sensitive topics require parental approval.
• A family assistant. Age-aware profiles, parental approval workflow, notification to parents via email/SMS/Slack/Discord/ntfy.

---

How it works

Family member sends message
  → via Telegram / WhatsApp / Discord / Web UI
    → FamClaw identifies user from gateway account
      → OPA policy evaluates: allow / block / request approval
        → if allow: forwards to your LLM endpoint
          → streams response back
- [Agent Setup Guide](./docs/AGENT_SETUP.md) — Complete setup instructions for AI coding agents

FamClaw itself uses ~20MB RAM. The LLM runs elsewhere — on a Mac Mini on your LAN, a cloud API, or any OpenAI-compatible server.

---

Hardware

Device	Role
Raspberry Pi 3/4/5	Run FamClaw 24/7, flash SD card and plug in
Mac Mini	Run as background daemon
Any Linux box	One binary, no dependencies

---

LLM backends

FamClaw talks to any OpenAI-compatible endpoint:

Platform	Backend	api_key needed
RPi 3/4/5	Ollama (local, auto-installed by firstboot.sh)	No
Mac Mini	Ollama (local)	No
Old Android (Termux)	OpenAI / Anthropic / OpenRouter / another device's Ollama	Yes (or LAN URL)
Any device	Can point at RPi's Ollama on LAN	No
Any device	Claude CLI (provider: claude_cli)	No (uses local claude binary)

llm:
  base_url: "http://192.168.1.10:11434"  # Ollama on your Mac Mini
  model: "llama3.2:3b"
  # Per-call LLM request timeout in seconds. Each chat/tool call gets its
  # own context deadline. Default: 300 (5 minutes).
  timeout_seconds: 300

  profiles:
    cloud:
      base_url: "https://api.openai.com/v1"
      model: "gpt-4o-mini"
      api_key: "${OPENAI_API_KEY}"

  # When a message carries an image attachment (a photo sent on Telegram
  # or Discord), FamClaw routes it to this LLM profile instead of the
  # normal per-user model — text-only messages always use the normal
  # endpoint. Set this to a vision-capable model (e.g. qwen2.5-vl,
  # llama3.2-vision, gemma3).
  #
  # When EMPTY, the per-user endpoint is used for images too. If that
  # model is text-only, the image is still sent to it but CANNOT be seen
  # — it is silently ignored (the assistant only receives the empty text),
  # which is why real deployments set vision_profile. Images are sent to
  # the configured LLM endpoint, which may be remote — they stay on-device
  # only when that endpoint is local.
  vision_profile: ""

Security note: llm.api_key is loaded from plaintext YAML by default. Set FAMCLAW_LLM_API_KEY environment variable to override — it takes precedence and avoids logging the plaintext warning.

---

Quick start

Raspberry Pi (flash and plug in)

# Flash famclaw-rpi4-arm64.img.xz to SD card with Raspberry Pi Imager
# Plug in, wait 2 minutes, find the device IP from your router and open:
http://<your-pi-ip>:8080

mDNS (famclaw.local) was removed in v0.5.x because it didn't resolve reliably on Windows or many home routers. Use the device's IP address from your router's DHCP leases page or ip addr on the Pi.

Mac / Linux

curl -fsSL https://github.com/famclaw/famclaw/releases/latest/download/install.sh | bash

Build from source

``