family-knowledge

🛡️ 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, 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 / 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

---

LLM backends

FamClaw talks to any OpenAI-compatible endpoint:

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:
      label: "OpenAI cloud (gpt-4o-mini)"  # display-only name shown in the web UI
      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: ""

Profile labels: the optional label on each profile is a display-only name shown in the web UI. Keep it accurate to where the profile actually routes (host + model), so a family member reading the label knows which model answers — a stale label (e.g. naming a model the profile no longer serves) misdescribes the routing.

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.

Reasoning auto-detection. When the endpoint is a LiteLLM (or OpenAI-compatible) gateway, FamClaw queries its model metadata at startup and learns each model's litellm_params.merge_reasoning_content_in_choices setting, so a final answer that ships in the reasoning field is shown to the family while chain-of-thought is filtered out — no per-model hand-configuration. Startup logs Auto-detect: N models discovered, or a warning when the gateway is unreachable (the built-in heuristic then applies, and later requests retry detection). Opt out or pin models with llm.reasoning (enable_auto_detect: false, litellm_url, per_model_override).

---

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

Download the binary for your platform from the latest release:

tar -xJf famclaw-darwin-arm64.tar.xz
touch config.yaml   # start empty — the web wizard fills it in
./famclaw --config config.yaml

Then open http://<host>:8080 and complete the setup wizard (it writes the rest of the config for you).

Release darwin binaries are Developer ID-signed and notarized when signing credentials are configured; without them the release falls back to ad-hoc-signed darwin binaries (a browser download needs Gatekeeper's right-click → Open on first run — docs/RELEASE.md). The tarballs verify against checksums.txt plus a cosign signature bundle. Upgrading an existing installation (atomic swap + service restart, never an in-place overwrite):

curl -fsSL https://raw.githubusercontent.com/famclaw/famclaw/main/scripts/update.sh | bash

Build from source

git clone https://github.com/famclaw/famclaw
cd famclaw
make build
./bin/famclaw --config config.yaml

---

Messaging gateways

Each family member's gateway account maps to their profile. Emma's Telegram account → Emma's age policy. Parent's Discord account → parent access.

File delivery. When the assistant produces a file in the conversation workspace (e.g. via file_write), it can attach and send it back into the same conversation through the send_file built-in tool — currently on Discord (the group channel or DM the user is in). Files are confined to the conversation sandbox, capped at 25 MiB (Discord's bot upload limit), and every delivery is audit-logged. Which roles may call the tool is decided by OPA tool_policy; on gateways without file support yet, the tool returns an honest "not available" error instead of silently dropping the request.

---

Policy system

Policies are OPA Rego files. The default rule set lives at internal/policy/policies/ and is embedded in the binary via go:embed — a downloaded release runs without any external policy directory. To override with custom rules, set policies.dir (and policies.data_dir) in config.yaml to a directory of your own .rego and JSON files. Run opa test internal/policy/policies/family/ internal/policy/policies/data/ -v to test the built-in rules locally.

Three tiers per age group:

allow        → goes straight to LLM
request_approval → parent gets notified, child waits
block        → never reaches LLM

Default age groups: under_8, age_8_12, age_13_17, parent.

---

Skills

FamClaw uses the [AgentSk