HomeBrain is a local-first home automation and voice-assistant platform. It combines a Node/Express backend, a React web app, optional local AI services, remote room listeners, and an optional iOS companion app into one self-hosted system.
- A web dashboard for devices, scenes, automations, workflows, voice devices, profiles, settings, reverse proxy/domains, operations, SSL inventory, Whisper, Ollama, and platform deploy
- Smart home integrations for SmartThings, Ecobee, INSTEON/ISY, and Logitech Harmony Hub
- Remote listener onboarding and fleet updates for room devices
- Wake-word training and distribution using OpenWakeWord plus Piper-generated training data
- Optional local speech-to-text with Whisper
- Optional local LLM support with Ollama
- An optional iOS app in
HomeBrainApp
HomeBrain is no longer Jetson-only.
- Best-tested hub: Jetson Orin Nano
- Also supported as a hub: other always-on Ubuntu/Debian
amd64orarm64machines - Best-tested listener: Raspberry Pi 4/5
- Also supported as a listener: other Debian/Ubuntu-based Linux mini PCs or SBCs with a microphone and speaker
What changes by hardware:
- Core web app, automations, integrations, and remote listeners work on generic Linux hardware.
- Jetson is still the best target for local GPU workloads such as Whisper and Ollama.
- Non-Jetson hosts can still run HomeBrain; local AI workloads may simply run slower or fall back to CPU.
- Clone your public repo to the hub machine.
- Run one installer script.
- Open HomeBrain in a browser on port
3000.
Jetson hub:
git clone <your-public-repo-url> HomeBrain
cd HomeBrain
bash scripts/install-jetson.shOther Ubuntu/Debian Linux hub:
git clone <your-public-repo-url> HomeBrain
cd HomeBrain
bash scripts/install-linux.shAfter the installer finishes:
- Open
http://<hub-ip>:3000 - Create your first account
- Continue with
docs/configuration.md
Important:
- Production HomeBrain serves the UI/API on internal port
3000 - Caddy is now the intended public edge on
80/443 - Port
5173is only used by the Vite dev server during local frontend development
- Beginner Jetson guide:
docs/jetson-setup.md - Full deployment guide:
DEPLOYMENT.md - Post-install configuration:
docs/configuration.md - Admin workflow:
docs/admin-guide.md - End-user voice usage:
docs/user-guide.md - Troubleshooting:
docs/troubleshooting.md - Wake-word setup:
docs/wake-word-setup.md - Remote listener guide:
remote-device/README.md - Docs index:
docs/README.md
From the HomeBrain UI:
- Open
Voice Devices - Click
Add Remote Device - Enter the room/device details
- Copy the generated one-command installer
- Run that command on the listener device
Raspberry Pi cloud-init onboarding is also available from the same dialog.
The installer writes and enables:
homebraincaddy-api
Useful commands:
bash scripts/setup-services.sh status
bash scripts/setup-services.sh logs follow
bash scripts/setup-services.sh health
bash scripts/setup-services.sh updatePublic HTTPS routing is managed from Reverse Proxy / Domains in the HomeBrain UI. The built-in Platform Deploy flow still deploys HomeBrain in place and keeps working behind Caddy because Caddy stays up while only the homebrain app service restarts.
Install dependencies:
npm installRun the backend:
npm run serverRun the frontend dev server:
npm run clientDevelopment ports:
- API/backend:
http://localhost:3000 - Vite frontend dev server:
http://localhost:5173
This repository is set up so secrets should stay local:
- real runtime secrets belong in
server/.env server/.envis gitignored- build output and generated download packages are gitignored
One thing git itself can still expose is commit author metadata. If you want to hide older author email addresses before publishing the full history, that requires a separate git history rewrite.
HomeBrain is licensed under the Apache License 2.0. See LICENSE.