Fulloch

[![GitHub Release][releases-shield]][releases] ![License][license-shield] [![hacs][hacs-shield]][hacs]

The Fully Local Home Voice Assistant — private, conversational, 100% on-device.

A voice assistant with agentic memory, web research, and smart-home control running entirely on your own GPU. Speech recognition, the language model, and the spoken voice never leave your machine.

Fulloch sits on top of your existing setup as the conversational brain — it drives Home Assistant for smart-home control and reads and writes plain Markdown notes, so it plugs straight into an Obsidian vault or any Markdown workflow.

Features

• Conversational — holds context across a turn; follow-ups like "and tomorrow?" just work
• Barge-in — interrupt the assistant mid-sentence with the wakeword
• Agentic memory — facts persist across restarts and build up over time
• Markdown notes — read, write, append, and search .md files by voice; point it at your Obsidian vault
• Semantic search — "what did I write about the car service?" via a local embedding model
• Conversation recall — "what did we talk about yesterday afternoon?" — summarises past turns from Home Assistant history
• Web research — live answers from a self-hosted search engine, summarised into a short spoken reply
• Smart-home control — lights, climate, media, calendar, weather, scenes, and entity history via Home Assistant; common commands (lights on/off, dim, colour, locks, blinds, volume) skip the model for an instant response, and any entity can be switched off for voice control from the dashboard
• Music search & play — "play the Beatles" via SpotifyPlus (required for search-by-name; basic playback control works with the built-in Spotify integration)
• Calendar reminders — creates events on a dedicated HA calendar and speaks them at the right time
• Thinking mode — "think about X" for a slower, deeper answer; interrupt to get a partial summary
• Cloned voice — speaks in a voice cloned from a few seconds of reference audio
• Web dashboard (optional) — type from your phone; voice and text share the same brain and history

The Local Stack

Minimum hardware: 16GB VRAM GPU (e.g. RTX 5060 Ti). The full pipeline is GPU-resident; there is no CPU fallback.

Home Assistant Integration

This integration will set up the following platforms.

Optional HA integrations

HA HACS Installation

Use the following link to open (and add) the Fulloch repository in HACS:

If the above does not work, add it manually:

• Go to HACS → three-dot menu → Custom repositories
• Paste https://github.com/liampetti/fulloch, select Integration, click Add
• Find the Fulloch entry and click Download
• Restart Home Assistant

HA Manual Installation

• Copy custom_components/fulloch/ into your HA config/custom_components/ directory
• Restart Home Assistant
• Go to Settings → Integrations → Add → Fulloch and enter your Fulloch host and dashboard port

HA Entities

HA Actions

HA Events

Use these in automations — e.g. dim lights on fulloch_wakeword_detected, restore on fulloch_turn_ended.

Proactive speech from automations

action: fulloch.speak
data:
  text: "The front door just opened."

action: fulloch.chat
data:
  text: "Tell me today's calendar and weather."

Restricting voice control

Some entities you may be happy to control from the secure dashboard but not by voice — door locks and alarms being the obvious cases. The dashboard's Entities tab lists every Home Assistant entity Fulloch knows about with a toggle each; switch one off and Fulloch will refuse to control it by voice (it speaks a short "that isn't available for voice control" instead of acting), while it stays fully usable from the dashboard and in your own HA automations.

Changes take effect immediately — no restart. The choices are stored in data/voice_denylist.json so they persist across restarts.

This is separate from Home Assistant's "Expose to Assist" setting, which only governs HA's built-in Assist and isn't readable by Fulloch. Use the Entities tab instead.

Fulloch Installation

Linux (Docker)

git clone https://github.com/liampetti/fulloch.git
cd fulloch
./launch.sh

On first run, creates data/config.yml and .env from templates, pauses for editing, downloads models, loads PulseAudio echo cancellation, and starts via Docker Compose.

Windows

git clone https://github.com/liampetti/fulloch.git
cd fulloch
pip install -r requirements.txt
launch.bat

SearXNG runs in Docker; the assistant runs natively in Python — no audio-passthrough complexity. Requires Python 3.10+, Docker Desktop, and an NVIDIA GPU with CUDA.

Dependencies

requirements.txt pins every direct dependency to an exact version for reproducible installs. The GPU stack (CUDA torch, plus the git-installed qwen-tts / flash-attn) can't be PyPI-locked cleanly, so there's no transitive lockfile — snapshot a known-good environment by freezing the built image:

docker compose run --rm app pip freeze > requirements.lock

Configuration

Everything lives in data/config.yml. Key settings:

general:
  wakeword: "hey atticus"         # activation phrase
  barge_in: "wakeword"            # "off" | "wakeword" (needs AEC)
  follow_up_time: "5s"            # wakeword-free reply window after TTS ends
  voice_clone: "atticus"          # data/voices/<name>.{wav,txt}
  dashboard_port: 8765            # web chat UI; remove to disable
  dashboard_host: "127.0.0.1"     # local-only; "0.0.0.0" to reach it from other devices
  # dashboard_ssl_certfile: "./data/certs/fulloch.pem"   # optional HTTPS (both keys required)
  # dashboard_ssl_keyfile:  "./data/certs/fulloch-key.pem"
  use_vad: true                   # drop non-speech buffers (coughs, taps) before ASR
  asr_context_hint: true          # bias ASR decoder toward wakeword spelling
  asr_context_terms:              # optional extra terms to bias (max 10)
    - "phoebe bridgers"

home_assistant:
  url: "http://192.168.1.50:8123"
  token: "your_long_lived_access_token"  # or set FULLOCH_HA_TOKEN in .env (preferred)
  calendar: "Fulloch"             # HA calendar for voice reminders (optional)

notes:
  path: "/path/to/obsidian/vault" # defaults to data/notes/
  daily_subdir: "daily"           # optional daily journal subfolder

search:
  searxng_url: "http://localhost:8080/search"

Full reference: data/config.example.yml

Secrets and tokens live in .env (not config.yml): SEARXNG_SECRET, FULLOCH_DASHBOARD_TOKEN (dashboard auth), and FULLOCH_HA_TOKEN (Home Assistant, overrides home_assistant.token). See .env.example.

Exposing the dashboard

The dashboard can read and write your notes, toggle the microphone, speak through your speakers, and drive Home Assistant — so it is unauthenticated and bound to 127.0.0.1 (local-only) by default.

To reach it from your phone or another device on your network:

1. Bind to your network — set general.dashboard_host: "0.0.0.0" in data/config.yml.
2. Require a token — set FULLOCH_DASHBOARD_TOKEN in .env (generate one with openssl rand -hex 32). This is mandatory: without it, anyone on your LAN gets full notes/mic/speech/Home-Assistant control, and Fulloch logs a warning at startup.
3. Open it once at http://<this-host-ip>:<port>/?token=<your-token> (find the IP with hostname -I). The browser stores the token and strips it from the address bar, so you can bookmark the bare http://<host>:<port>/ afterwards. If the token is missing or wrong, the page prompts you for it.

Optional: HTTPS

Over plain HTTP the token travels in clear text — fine o