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
• Cloned voice (GPU override) - speaks in a voice cloned from a few seconds of reference audio; the default CPU stack uses fast built-in named voices (Kokoro) instead

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

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.

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 http://localhost:8765 and follow the wizard.

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.

Important: If you are using an OpenAI endpoint you will lose the GBNF enforced JSON formatting that comes with the built-in LLM. This means there is a higher risk of tool call errors when running the LLM remotely.

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/fulloch, category Integration → Download → restart HA → Settings → Integrations → Add → Fulloch.

Use events in automations, e.g. dim lights on fulloch_wakeword_detected, restore on fulloch_turn_ended. Use fulloch.speak for proactive notifications from your home.

The dashboard's Entities tab blocks specific entities (locks, alarms) from voice control without affecting dashboard or automation access. Changes apply immediately.

Search-by-name music queries ("play the Beatles", "play jazz in the kitchen", "play music everywhere") need a spotify: block in config.yml, Fulloch searches Spotify directly via the Web API, then hands the resolved track/playlist off to a Home Assistant media_player entity to actually play. Requires a one-time manual OAuth step to get a refresh token. See the spotify: section in data/config.example.yml for the config keys and data/credentials.json fields. Without a spotify: block, there's no music search, pause/resume/skip still work through Home Assistant regardless (so they keep working for AVR/TV too).

Obsidian Integration

Connect your Obsidian vault so Fulloch reads, writes, appends, and searches your notes by voice, and knows which note you have open. The first time you connect, Fulloch offers to copy your existing notes into the vault as Inbox/fulloch-import/. Cloud sync (Remotely Save, etc.) is unchanged, Fulloch only sees the local vault.

Setup (about 2 minutes):

1. In the Fulloch setup wizard, the "Connect Obsidian" step lets you auto-detect your vault or paste its path. Click Save and continue, or Skip to do it later.
2. Open the dashboard's Obsidian tab and click Show install instructions to get a download link and your auth token.
3. In Obsidian, extract the downloaded plugin.zip into <your-vault>/.obsidian/plugins/fulloch/, then enable the Fulloch plugin in Settings → Community plugins and paste the token.

That's it. Once the plugin connects, the dashboard flips to Connected and voice notes go straight to your vault. Closing Obsidian doesn't break anything, Fulloch remembers the vault and voice keeps working.

To point Fulloch at a different vault later, use the Switch vault section on the Obsidian tab.

Running Fulloch in Docker? The plugin runs on the host, so it reports host paths (e.g. /Users/you/Documents/MyVault). Fulloch inside the container can't see those. Two edits to wire it up:

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

2. Add the same mapping under obsidian.path_translation in data/config.yml:

   obsidian:
     path_translation:
       "/Users/you/Documents/MyVault": "/vault"
   

Restart Fulloch. The Obsidian wizard's "Auto-detect" scans the container filesys