Gladys Assistant

Gladys Assistant is a privacy‑first, open‑source smart‑home platform that runs entirely on your own hardware. From a developer’s perspective, it exposes a RESTful API, a WebSocket event bus, and a rich plugin architecture that lets you extend the core with custom services or integrations. The system is built to be event‑driven: sensors, devices, and user commands all trigger states that propagate through the internal workflow engine, enabling complex automations without writing code. This model makes Gladys an attractive choice for developers who want to prototype home‑automation logic in a declarative manner while still having full control over the underlying data.

Gladys is written in Node.js (v18+) and uses the NestJS framework for its modular architecture. The core runtime is a single process that orchestrates several micro‑services (device manager, automation engine, UI server) via an internal Redis message broker. Persisted state lives in a lightweight SQLite3 database, but the codebase supports swapping to PostgreSQL or MySQL for larger deployments. Device discovery and communication rely on standard protocols such as Zigbee, Matter, MQTT, and proprietary APIs (e.g., Shelly, Sonos). The UI is a React SPA served from the same Node process, offering real‑time updates through WebSockets. Docker images are provided for quick deployment, but the application can also be run natively on ARM or x86 hardware.

• Automation Engine – A rule‑based engine that evaluates triggers (time, sensor state, external events) and executes actions. Rules are defined in JSON/YAML or via the UI and can call external webhooks.
• Device Integration – Plug‑in support for Zigbee, Matter, MQTT, and a growing list of community devices. Each integration exposes a consistent API for reading state and sending commands.
• Voice & Messaging – Built‑in adapters for Telegram, Google Home, Alexa, and Siri. Developers can add custom voice assistants by implementing the adapter interface.
• Webhooks & APIs – Exposes a REST API for CRUD operations on devices, automations, and users. Webhooks can be subscribed to device events or automation outcomes.
• Extensibility – The plugin system allows developers to ship new integrations as NPM packages that register with the core at runtime. The SDK provides hooks for lifecycle events, telemetry, and custom dashboards.

Gladys is designed to run on modest hardware such as a Raspberry Pi, a NAS, or a mini‑PC. The Docker image bundles all dependencies, and the provided docker run command mounts a local SQLite file for persistence. For larger deployments, Docker Compose or Kubernetes can be used to scale the Redis broker and separate the UI from the core. The application supports automatic upgrades via the Docker image tag latest, and developers can roll back to a previous version by pulling an older tag. Because all data stays on the host, there is no external network dependency unless a specific integration requires it.

Gladys’ plugin architecture is the linchpin for extensibility. Each plugin declares a manifest (package.json + gladys-plugin.yaml) that lists supported device types, services, and optional UI components. The core loads these manifests at startup, validates them against the schema, and injects the plugin’s services into the dependency graph. Developers can also expose custom dashboards using React components that are hot‑reloaded by the core. For advanced use cases, the SDK allows hooking into the event bus to listen for specific state changes or to trigger external APIs.

The documentation is organized around setup, contributing, and service development. The developer guide walks through setting up a local environment, explains the folder layout (services, plugins, common), and provides a checklist for creating a new service. The community is active on GitHub, Discord, and the official forum, which helps in troubleshooting integration bugs. Licensing is MIT, so commercial usage poses no restrictions. The UI is intentionally minimal to keep the focus on APIs and automation logic, yet it includes a built‑in automation editor that visualizes rules as flow charts.

1. Home Automation Hub – Centralize all Zigbee, Matter, and MQTT devices under one roof, exposing a unified REST API for home‑automation apps.
2. Custom Voice Assistant – Build a bespoke Alexa skill that talks directly to Gladys’ event bus, bypassing cloud services.
3. Edge‑Computing IoT Platform – Deploy Gladys on a Raspberry Pi to process sensor data locally, reducing latency for time‑critical actions.
4. Enterprise Smart Building – Scale the core with Redis clustering and swap SQLite for PostgreSQL to manage dozens of rooms, devices, and users.

• Privacy‑First – All data remains on local hardware; no cloud provider is required.
• Performance – Node.js + NestJS + Redis yields sub‑second event propagation, ideal for real‑time automations.
• Extensibility – The plugin system lets developers ship new device integrations as simple NPM packages.
• Zero Configuration UI – No need to edit config files; everything is managed through the web interface or API.
• Community‑Driven – Rapid iteration, open discussions, and a wealth