Fulloch

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

The Fully Local Home Voice Assistant, a private voice layer for your notes, your home, and the web.

Fulloch is your privacy-focused local voice assistant running on your own PC or Mac. Ask questions, capture thoughts, and search your Obsidian vault by voice. Control your home via Home Assistant. Pull live answers from the web with SearXNG. The local stack keeps speech, language processing, notes, facts, and conversation history on your machine; optional web search, Spotify, and remote language models contact their configured services.

Click here to see the satellite companion project for running multiple ESP32-S3 satellites around your home.

Features

• Private, local by default - speech, language processing, notes, facts, and conversation history stay on your machine; web search, Spotify, and remote language models are explicit opt-ins
• Natural voice conversations - use the browser dashboard or connected satellites; Fulloch keeps conversational context, supports follow-up turns, and lets you barge in with the wakeword
• Your voice, your way - GPU and CPU stacks support voice cloning; ask it to whisper or speak quietly for per-turn reduced-volume delivery
• Obsidian notes and memory - read, write, append, and semantically search your vault by voice; remembered facts persist across restarts
• Smart-home control - control Home Assistant lights, locks, covers, climate, media, calendars, todos, weather, and more in natural language
• Music and reminders - find music with Spotify and play it through Home Assistant; create calendar reminders that Fulloch announces at the right time
• Live answers - get concise, source-aware summaries from self-hosted SearXNG web search, with the option to save results to your vault
• Deliberate research and planning - queue deeper background investigations for comparisons, academic literature, travel, and finance; research prefers Semantic Scholar and falls back to arXiv and OpenAlex, while optional SerpApi-backed travel and finance tools provide bounded, read-only results
• Home Assistant automation - use the HACS integration for status, mic control, proactive speech, chat, and scheduled deliberate-thinking tasks

Higgs TTS 3: The optional Higgs GPU backend is available only under Boson AI's Research and Non-Commercial License, not Fulloch's MIT license. It requires explicit consent for every voice reference. See Model Sources and Licenses.

Pocket TTS PyTorch: The experimental GPU streaming option uses Kyutai's official gated model. Accept its Hugging Face terms before selecting it. If the download is denied, the wizard prompts for a Hugging Face read token, saves it in data/credentials.json, and retries. See Model Sources and Licenses.

openWakeWord feature extractors: The optional wakeword gate includes unmodified pre-trained feature extractor models from openWakeWord v0.5.1 under CC BY-NC-SA 4.0, not Fulloch's MIT license. See Model Sources and Licenses.

Quick installation

The default stack runs on CPU (mac/linux/windows). Audio runs through the browser dashboard. The LLM is either regex-only (simple commands) or off-box via an OpenAI-compatible endpoint you configure in the wizard (e.g. Ollama / LM Studio / another machine on your LAN). The dashboard avatar swaps to Parloch, the Partially-local home voice assistant, when the LLM is running off-device.

Install Docker Desktop (or Docker Engine) first. The first run downloads the selected speech models, so it needs an internet connection, several GB of free disk, and enough Docker memory for the wizard's displayed estimate. For the GPU image, install a current NVIDIA driver and NVIDIA Container Toolkit, then confirm docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi works before launching Fulloch.

CPU (mac/linux/windows)

docker run -d \
  --name fulloch-ai \
  --restart unless-stopped \
  --log-opt max-size=10m \
  --log-opt max-file=5 \
  -p 8765:8765 \
  -p 8766:8766 \
  -e DASHBOARD_HOST=0.0.0.0 \
  -v fulloch-data:/app/data:rw \
  ghcr.io/liampetti/fulloch:cpu

The named volume is repaired automatically on first boot and receives the bundled starter voice references. If you prefer a bind mount, use an existing writable directory such as -v "$PWD/data:/app/data:rw"; see data-directory permissions if startup reports a permission error. Open the HTTPS URL shown in docker logs fulloch-ai in a browser to continue the setup wizard. A self-signed certificate warning is expected on first visit; accept it to enable browser microphone access. The dashboard is LAN-visible with this command, so set a dashboard password in the wizard before using it beyond a trusted network.

Add -v /path/to/your/ObsidianVault:/vault:rw before the image name to expose an Obsidian vault.

GPU (Linux/Windows + NVIDIA)

Swap :cpu for :latest (the CUDA image with Qwen3-TTS voice cloning and the on-GPU 9B SLM) and add --gpus all:

docker run -d \
  --name fulloch-ai \
  --restart unless-stopped \
  --log-opt max-size=10m \
  --log-opt max-file=5 \
  --gpus all \
  -p 8765:8765 \
  -p 8766:8766 \
  -e DASHBOARD_HOST=0.0.0.0 \
  -v fulloch-data:/app/data:rw \
  ghcr.io/liampetti/fulloch:latest

OpenAI Endpoint

The moment you point the language model at an OpenAI-compatible endpoint, the avatar and favicon swap to a travelling version of the character (Let's call him Parloch: The Partially local home voice assistant), and the tagline reads "language model is off-device." Pick a local model again (None or the GPU 9B) and Fulloch comes home. It triggers as soon as a remote endpoint is configured, even if it is on your home network.

Recovering Or Reconfiguring

Use Settings for normal changes: voices, model backends, language-model mode, Home Assistant, Search, and dashboard preferences. Model changes need a restart; if their weights are missing, the restart returns to the wizard to download them. The Re-run setup wizard action makes a backup under data/backups/; use it to choose a different stack, not to edit a custom model path or advanced remote-LLM settings. To repair a failed download, re-run setup and select the same stack; incomplete model caches are detected and downloaded again.

Advanced options not shown in Settings are documented in data/config.example.yml: Spotify OAuth, native satellite tokens, and external-LLM timeouts. Keep those files under the persistent data volume.

Obsidian Integration

Connect your Obsidian vault so Fulloch reads, writes, appends, and searches your notes by voice.

Just add your vault's directory as a volume when launching Docker container -v /Users/you/Documents/MyVault:/vault:rw

The Obsidian wizard's "Auto-detect" scans the container filesystem for a vault, so it'll find /vault (or wherever you mounted it) without further config.

The plugin is optional: the folder link alone supports reading, writing, appending, and searching notes. Install the separate plugin for live active-note and selection context, editor actions, and automatic note navigation; Docker installations with different host and container paths cannot yet navigate back to a written note automatically. See the Obsidian setup details.

Home Assistant Integration

When Fulloch runs in Docker, enter Home Assistant's LAN address, for example http://192.168.1.50:8123. localhost refers to the Fulloch container, not Home Assistant.

A HACS-installable integration for status sensors, mic control, proactive speech, and automation triggers.

Instant Commands

Common commands take a regex fast-path that skips the language model entirely, for an instant response. Compound requests ("… and …"), vague references ("turn it off"), or conve