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 fully private, 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. All fully private and running on your home PC.

Features

• Obsidian notes - read, write, append, and search your vault by voice; capture a conversation as a note without leaving what you're doing
• Semantic search - "what did I write about the car service?" finds the right note by meaning, not just keywords
• Web search - ask a question, get a spoken summary pulled live from a self-hosted search engine, optionally saved to your vault
• Conversational - holds context across a turn; follow-ups like "and tomorrow?" just work
• Memory - facts persist across restarts and build up over time
• Smart-home control - control any of your smart home devices using Home Assistant, integrate Fulloch into Home Assistant to trigger voice notifications and track your conversational history
• Music search & play - "play the Beatles", "play jazz in the kitchen", "play music everywhere" - smart search on Spotify directly and hand playback off to Home Assistant
• Calendar reminders - creates events on a dedicated HA calendar and speaks them at the right time
• Barge-in - interrupt mid-sentence with the wakeword
• Voice options - the GPU stack clones from reference audio; CPU users can choose fast built-in Kokoro voices or experimental Pocket TTS one-shot cloning
• Quiet delivery - ask it to whisper or speak quietly; every TTS backend lowers output volume to 30% by default

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.

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.

CPU (mac/linux/windows)

docker run -d \
  --name fulloch-ai \
  --restart unless-stopped \
  -p 8765:8765 \
  -e DASHBOARD_HOST=0.0.0.0 \
  -v ./data:/app/data:rw \
  # -v /path/to/your/ObsidianVault:/vault:rw \
  ghcr.io/liampetti/fulloch:cpu

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 \
  --gpus all \
  -p 8765:8765 \
  -e DASHBOARD_HOST=0.0.0.0 \
  -v ./data:/app/data:rw \
  # -v /path/to/your/ObsidianVault:/vault:rw \
  ghcr.io/liampetti/fulloch:latest

RTX 50-series: Native MTP speculative decoding and llama.cpp's built-in FlashAttention are disabled on Blackwell because llama.cpp can fault on longer agent prompts. This does not affect the Python FlashAttention 2 dependency used by the GPU speech models.

The commented-out -v line exposes your Obsidian vault to Fulloch so voice notes can read/write it. Uncomment it, edit the host path, and add a matching obsidian.path_translation entry in data/config.yml, see the Obsidian section below.

Named volumes (e.g. -v fulloch-data:/app/data:rw in compose) work too, the image's entrypoint chowns the volume to the container's user on first boot, so no separate chown init container is needed. The bind mount above (the default in this README) inherits the host's UID and is even simpler.

SearXNG sidecar (optional, for live web answers)

Create a shared network, then run SearXNG on it and point Fulloch at it via search.searxng_url:

docker network create fulloch
docker run -d \
  --name searxng \
  --network fulloch \
  --restart unless-stopped \
  -p 8080:8080 \
  -e SEARXNG_SECRET=change-me \
  searxng/searxng

Then in the Fulloch setup wizard, set Web search URL to http://searxng:8080/search. (Skip the -p 8080:8080 if you don't need to reach SearXNG from the host, the Fulloch container only needs the in-network name.)

Once launched

• Open https://localhost:8765 and follow the wizard. See First 2 minutes below for a step-by-step walkthrough of what to expect.

First 2 minutes

What the first two minutes of a fresh install actually look like, so nothing in the timeline surprises you:

1. docker run returns in a second. The container starts and the entrypoint chowns the data dir (a no-op on bind mounts; fixes named volumes on first boot). The image is ~2 GB for the CPU stack and ~6 GB for the GPU stack; only download size, not memory.
2. Open https://localhost:8765. The dashboard's first render shows the URL banner with a Copy button and a one-line note about the self-signed-cert warning. Click through the warning; it's expected for a private LAN install.
3. Walk the wizard. Four steps: pick a thinking mode (regex simple / full GPU / remote LLM), pick a name and voice, optionally connect Home Assistant and SearXNG, optionally connect Obsidian.
4. Models download. This is the long bit. The CPU stack pulls roughly 5 GB (Qwen3 1.7B ONNX + Kokoro 82M); choosing Pocket TTS instead adds its roughly 250 MB English ONNX voice-cloning bundle. The GPU stack pulls roughly 13 GB (Qwen3 1.7B PyTorch ASR + Qwen3 1.7B PyTorch TTS + the 9B language model).
5. Startup Once models are downloaded the assistant can go through startup, this will happen everytime you stop and restart Fulloch. This should only take about a minute or two with the Qwen3 TTS taking the longest to warm-up. Once everything is loaded you are presented with the chat screen. You can type text or click to activate voice mode, if you also select "Always Listen" you do not need the wakeword anymore (default is 'Hey Atticus').

Trusted LAN HTTPS

The default certificate is self-signed, which is enough for browser microphone permission after accepting the warning once. To remove that warning on home network devices, create a private Fulloch CA and dashboard certificate:

python scripts/create_local_ca.py --force

The script writes the dashboard certificate to data/certs/dashboard.crt, so it uses the existing HTTPS configuration. It prints the one-time trust command for Linux, macOS, Windows, iOS/iPadOS, and Android. Install only data/certs/fulloch-home-ca.crt on client devices; never distribute fulloch-home-ca.key. Restart Fulloch after running the script. Add extra names or addresses before clients use them, for example:

python scripts/create_local_ca.py --force --host fulloch.home --ip 192.168.1.20

Configuration

The setup wizard configures Fulloch on first boot, and the settings console (gear icon, the same web UI) edits every option afterwards. Everything is reachable from the UI: wakeword, barge-in, voice, the Home Assistant connection, notes path, and web search. But if you'd rather hand-edit, the full annotated reference is data/config.example.yml.

Secrets (HA token, LLM API key, dashboard password) are stored in data/credentials.json, written by the setup wizard. Copying data/ to a new machine transfers everything. To configure headlessly, copy data/credentials.example.json to data/credentials.json and fill in the values, or set the equivalent env vars (HA_TOKEN, LLM_API_KEY, DASHBOARD_PASSWORD, OBSIDIAN_TOKEN) in .env.

Web Dashboard

The web dashboard is unauthenticated and bound to 127.0.0.1 by default. To reach it from another device, set dashboard_host: "0.0.0.0" in config and set a password in the setup wizard's finish step.

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.

Note: GBNF grammar is passed through to llama.cpp-family servers (llama-server, LM Studio, Unsloth Studio), so the remote path enforces the same action/reply shape as the local one. Other OpenAI-compatible endpoints ignore the undocumented grammar field and fall back to response_format: json_object plus a one-shot repair round-trip, so tool-call errors are more likely there.

Home Assistant Integration

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

Or manually: HACS → Custom repositories → paste `https://github.com/liampetti/ful