English | Deutsch

Why Renfield?

• Voice-first with physical satellites — Raspberry Pi Zero 2 W + ReSpeaker HAT in every room (~$30/satellite). Wake word, STT, TTS — fully local.
• 10 MCP servers, 100+ tools, Agent Loop — Weather, search, news, calendar, smart home, media, DLNA, documents, email, workflows. ReAct agent chains tools autonomously for complex queries.
• Fully offline, self-hosted, GDPR-friendly — Runs entirely on your hardware. No cloud dependencies. Your data never leaves your network.

Screenshots

Features

Core

• Chat interface with streaming responses, conversation history, inline album art, collapsible agent steps
• ReAct Agent System with specialized roles, multi-step tool chaining, and media transport shortcuts
• Knowledge Graph — entity-relation triples with post-extraction validation, string-similarity dedup, and bulk cleanup API
• Conversational memory — long-term recall of preferences, facts, and instructions with contradiction detection
• Intent feedback learning — learns from corrections via semantic matching (3-scope: intent, tool, complexity)
• Voice I/O — Whisper STT + Piper TTS + SpeechBrain speaker recognition
• Presence detection — BLE scanning, voice recognition, and web auth track who's in which room
• Proactive notifications — webhook-based alerts from Home Assistant/n8n + generic MCP notification polling
• Paperless audit — automated LLM-based metadata validation with review queue, OCR quality scoring, and auto-fix
• Hook/Plugin system — async extension API for custom integrations without modifying core

Integrations (10 MCP Servers)

Knowledge Base (RAG)

• Hybrid search — dense embeddings (pgvector) + BM25 full-text (German FTS, OR matching), combined via RRF
• Formats — PDF, DOCX, PPTX, XLSX, HTML, Markdown, TXT (with EasyOCR fallback for garbled PDFs)
• Knowledge bases — thematic collections with sharing and access control
• Agent tool — knowledge_search for combined RAG + Paperless search within the agent loop
• Knowledge Graph — entity-relation triples with post-extraction validation, string-similarity dedup, bulk cleanup API, admin dashboard

Multi-Room Voice Satellites

• Local wake word detection (OpenWakeWord)
• Audio output routing to best device per room (Renfield, HA, DLNA)
• IP-based room context detection

Presence Detection

Multi-source room-level presence tracking:

• Privacy-aware TTS — notifications respect room occupancy (public / personal / confidential)
• Automation hooks — enter_room, leave_room, first_arrived, last_left events fire webhooks for n8n / Home Assistant
• Presence dashboard — real-time room occupancy in the admin UI

Security & Access Control

• Role-permission based access control (RPBAC) with JWT
• Rate limiting, circuit breakers, trusted proxy support
• Docker secrets management for production

Platform

• Progressive Web App (desktop, tablet, mobile)
• Dark mode (light, dark, system)
• Multilingual (German, English)
• Prometheus metrics (opt-in)

Quick Start

git clone https://github.com/ebongard/renfield.git && cd renfield
cp .env.example .env                          # configure your settings
docker compose up -d                          # start the stack
docker exec -it renfield-ollama ollama pull qwen3:8b  # download LLM

Open http://localhost:3000 and start chatting.

For GPU acceleration, use docker compose -f docker-compose.prod.yml up -d with NVIDIA Container Toolkit.

Architecture

Configuration

All settings via .env, loaded by Pydantic Settings. See docs/ENVIRONMENT_VARIABLES.md for the full reference.

LLM (Multi-Model)

Separate models for different tasks:

OLLAMA_URL=http://ollama:11434
OLLAMA_CHAT_MODEL=qwen3:14b       # chat responses
OLLAMA_INTENT_MODEL=qwen3:8b      # intent recognition
OLLAMA_RAG_MODEL=qwen3:14b        # RAG answers
OLLAMA_EMBED_MODEL=nomic-embed-text  # embeddings (768 dim)

See docs/LLM_MODEL_GUIDE.md for model recommendations.

Key Settings

AGENT_ENABLED=false               # ReAct agent loop (opt-in)
MEMORY_ENABLED=false              # long-term memory (opt-in)
AUTH_ENABLED=false                 # RPBAC auth (opt-in)
MCP_ENABLED=true                  # master switch for integrations
PRESENCE_ENABLED=false            # room presence detection (opt-in)
KNOWLEDGE_GRAPH_ENABLED=false     # entity-relation extraction (opt-in)
NOTIFICATION_POLLER_ENABLED=false # proactive MCP notifications (opt-in)
METRICS_ENABLED=false             # Prometheus /metrics (opt-in)

Development

make lint                    # lint all code (ruff + eslint)
make test                    # all tests
make test-backend            # backend tests (2,100+)
make test-frontend-react     # React tests (Vitest + RTL)
make test-coverage           # tests with coverage report

See CONTRIBUTING.md for the full development guide.

Docker Compose Variants

Documentation

Disclaimer

Renfield is an independent open-source project. It is not affiliated with, endorsed by, or connected to any third party, organization, company, or brand with the same or similar name.

Acknowledgments

• Ollama — Local LLM inference
• Whisper — Speech-to-text
• Piper — Text-to-speech
• SpeechBrain — Speaker recognition (ECAPA-TDNN)
• IBM Docling — Document processing for RAG
• pgvector — Vector similarity search
• Home Assistant — Smart home platform
• n8n — Workflow automation
• SearXNG — Metasearch engine
• OpenWakeWord — Wake word detection

License

MIT License — see LICENSE file.

Contributing

Contributions are welcome! Please read our Contributing Guide and check the good first issues.