A self-hosted dashboard for smart-home devices, automations, and sensor history.
Get started · Setup guide · API & MCP · Contributing
NodeHerder connects a Go backend and Vue/TypeScript frontend to MQTT and Zigbee2MQTT. Manage devices from the browser, build automations, and explore recorded measurements. An optional assistant integration and MCP server expose household context and metrics to compatible clients.
- View device state, availability, exposes, and controls in grouped dashboards.
- Create device-triggered and scheduled automations with conditions and actions.
- Explore sensor history with zoom, daily sample statistics and CSV export; configure retention and quiet noisy readings with category defaults.
- Inspect hub logs and manage bridge joining and device settings.
- Query metrics through HTTP or MCP; connect an external assistant service with conversation history.
Metrics recording and MCP are disabled in the default configuration; enable them in settings. Assistant chat needs an external service URL.
flowchart LR
Devices["Zigbee devices"] <--> Z2M["Zigbee2MQTT"]
Z2M <--> MQTT["MQTT broker"]
MQTT <--> Backend["Go backend"]
Backend <--> UI["Vue dashboard"]
Backend --> Storage["Local settings, metrics & history"]
Client["MCP client"] <--> Backend
Backend <--> Assistant["Optional assistant service"]
The backend handles device updates, automations, persistence, and HTTP/WebSocket/MCP interfaces. The browser receives live updates over WebSocket. Assistant inference runs in the configured external service.
Use Node from .nvmrc. Create frontend/.env.development.local:
VITE_API_BASE_URL=http://localhost:4110/api
VITE_WS_BASE_URL=ws://localhost:4110/wsStart the fixture-backed mock server:
cd frontend
npm ci
npm run test-serverIn another terminal, run npm run dev from frontend/ and open
localhost:4100. The mock includes a simulated sign-in flow;
it is development tooling with partial API coverage, not a real-device backend.
Follow the setup guide for a Linux Docker host with a Zigbee coordinator, Mosquitto, and Zigbee2MQTT. It covers environment files, authentication, persistent data, local backend development, and frontend deployment.
Once configured, use the stack manager:
./scripts/manage-stack.sh rebuild all --dry-run # Preview without Docker changes
./scripts/manage-stack.sh rebuild all # Build, then apply
./scripts/manage-stack.sh status
./scripts/manage-stack.sh logs backend --tail 50The Compose stack publishes backend, MQTT, and Zigbee2MQTT ports. Context/MCP routes are currently public, and a local offline sign-in route exists. Keep deployment behind trusted-network access controls; see deployment details.
Use Go from backend/go.mod and Node from .nvmrc.
Run both services in one terminal (after npm ci in frontend/):
node scripts/dev.mjsThis builds the native backend and starts it alongside Vite. Ctrl+C stops both;
either service exiting also stops the other. Supports macOS/Linux. Backend changes
need a restart; frontend changes hot reload. Uses existing environment files, with
APP_ENV defaulting to development. Follow the local development setup
for MQTT/environment configuration and set frontend local API/WS URLs to that backend.
Ports must be free; this command does not start Docker or the mock server.
# From backend/
go test ./...
go build ./...
# From frontend/ (after npm ci)
npm test -- --runInBand
npm run lint
npm run buildCI checks tests, lint, builds, backend races, deployment tooling, and Docker images
on Ubuntu; see checks and merge requirements. The SDD guide explains specs,
plans, tasks, and review gates. Start behavior changes with a spec; use $sdd-plan
for implementation planning. Constitutions are proposed for maintainer adoption.
| Need | Start here |
|---|---|
| Installation, configuration, deployment, troubleshooting | Setup |
| Metrics API, MCP, assistant integration | Integrations |
| Code layout and important behavior | Repository map |
| Device update pipeline | Architecture |
| Development policy and templates | SDD · Constitution |
| Agent instructions and scoped rules | AGENTS.md |
| Backlog | TODO.md |