Horseflow is a self-hosted dictation tool that records on a hotkey, uses local Whisper for transcription, then cleans up with a local LLM before pasting the result into the focused app. It includes Linux and macOS clients and runs a server with Docker Compose.
Collecting history — the radar snapshots this repo daily. The trend line appears after 3 days of data (1 so far).
What it is
Horseflow is a self-hosted push-to-talk dictation system. It records while a global hotkey is held, transcribes locally with Whisper, cleans punctuation and false starts with a local LLM, then pastes the result into the focused application. It operates without cloud APIs and can run the server and clients on the same machine or over a private network.
How it works
Architecture: keyboard hotkey -> local recording -> Horseflow API -> Whisper large-v3 -> Ollama cleanup model -> clipboard -> synthetic paste. The server and clients may run on the same machine or communicate over a private network such as Tailscale. The Linux client uses evdev to capture input, pipes/mounts through PipeWire, and pastes via ydotool; the macOS client uses a native app to record and paste. The server requires Docker Compose, NVIDIA GPU with the NVIDIA Container Toolkit, and approximately 11 GB VRAM for Whisper large-v3 plus a quantized LLM.
Getting started
Install and run the server (example commands):
cd deploy
cp .env.example .env
nvidia-smi --query-gpu=uuid,name --format=csv
Edit .env, setting HORSEFLOW_GPU, HORSEFLOW_BIND_ADDRESS, and model paths. Start the stack:
docker compose up -d ollama
docker compose exec ollama ollama pull qwen3:8b
docker compose up -d --build api
curl http://127.0.0.1:8100/health
The API docs are at /docs. For cross-machine setups, use Tailnet HTTPS endpoints like:
https://horseflow-server.example-tailnet.ts.net/dictate
Linux client installation and usage is:
mkdir -p ~/.config/horseflow
cp clients/linux/client.env.example ~/.config/horseflow/client.env
clients/linux/install.sh
journalctl --user -u horseflow.service -f
Hold Ctrl+Space to record, speak, and release a key to paste.
macOS client installation is:
clients/macos/install.sh \
https://horseflow-server.example-tailnet.ts.net/dictate
Getting started (continued) – Configuration
Server settings are environment variables. Key variables include:
- OLLAMA_URL (required) – Ollama base URL
- HORSEFLOW_LLM_MODEL (required) – Cleanup model
- HORSEFLOW_ASR_MODEL (optional) – Whisper model; default
large-v3 - HORSEFLOW_LANGUAGE (optional) – Transcription language; default
en - HORSEFLOW_COMPUTE_TYPE (optional) – Whisper compute type; default
float16 - HORSEFLOW_DICTIONARY (optional) – Comma-separated vocabulary
- HORSEFLOW_ASR_PROMPT (optional) – Natural-language ASR context
Recent releases
RELEASES (latest 0): - none
Traction
Stars: 19 Forks: 0 Open issues: 0
Behind the repo
No linked startup/company information provided in the README.
Caveats
License: MIT. The server requires Linux with Docker Compose and an NVIDIA GPU with the NVIDIA Container Toolkit; approximately 11 GB VRAM for Whisper large-v3 and an 8B/9B quantized LLM. The Linux client requires Python 3.10+ and several external tools (pw-record, wl-copy, ydotool, notify-send) and may require user group memberships. The macOS client requires macOS 15+ and Xcode Command Line Tools. No authentication is implemented in Horseflow, and exposure should be limited to localhost or a private network.