Gladys Assistant Documentation

External integrations in Gladys Assistant run as isolated Docker containers within a dedicated bridge network (gladys-integrations). The system uses a Supervisor (server/lib/external-integration/) to manage the lifecycle of these containers (States: Installée → Démarrage → En fonctionnement → Dégradée → En panne → Arrêtée).

Key architectural components:

• Host API (REST): Accessible via /api/integration/v1/*, used by integrations to interact with the core (e.g., saveState, gladys.variable).
• WebSockets (WS): An extension of the WebsocketManager used for real-time communication (commands, scan requests, device notifications, and lifecycle pings/pongs).
• Data Model: An external integration is treated as a service in the database (a row in t_service with type: 'external') to avoid identity synchronization issues.
• Security: Integrations use stateless JWT authentication (not linked to a user) which is regenerated upon container recreation. They are sandboxed via Docker and have no access to the Docker socket.

Gladys Assistant uses a decoupled architecture for external integrations. The ecosystem consists of five primary repositories that interact via defined contracts:

• GladysAssistant/Gladys (monorepo): Acts as the Supervisor, API host, WebSocket provider, server-side store, and frontend. It hosts the integration supervisor logic.
• GladysAssistant/integration-store: The canonical owner of the manifest.schema.json. It uses a GitHub Action to index integrations and publishes an index.json to Pages.
• GladysAssistant/integration-sdk-js: The official npm package @gladysassistant/integration-sdk. It is designed to be lightweight and depends only on the integration contracts, not the Gladys monorepo.
• GladysAssistant/integration-template-js: The official template repository used to bootstrap new integrations and serve as a Proof of Concept (PoC).
• GladysAssistant/v4-website: The public documentation site (available in FR and EN).

External integrations in Gladys Assistant run as isolated containers managed by a supervisor. This architecture provides high flexibility and security through several key mechanisms:

• Lifecycle Management: Integrations can be set to start: "auto" (starts automatically with Gladys) or start: "manual" (requires an explicit API call to POST /container/:name/start).
• Network Isolation: Each integration gets its own private bridge network (gladys-int-<selector>). Sub-containers can communicate with each other using DNS aliases (the container name), but they cannot access the host API or other integrations.
• Port Management: Gladys automatically assigns and persists host ports for any declared ports to prevent collisions. Integrations can retrieve their assigned port via GET /container.
• Data Confinement: Volumes are mounted from a specific path: <basePath>/external-integrations/<selector>/containers/<name>/<path>. The main container sees these under /data/containers/<name>/..., which is the intended channel for runtime configuration files.
• Hardware Access: Hardware access (e.g., gpu, video, coral-usb) is requested via a manifest using named classes. Users must grant permission via the Gladys UI before the hardware is mounted into the container.

To allow third-party services to push events to a local Gladys instance (which is not reachable from the internet), you can use the Gladys Plus gateway. This is achieved by declaring webhooks in your integration's manifest. The gateway relays incoming HTTP requests to your integration via WebSockets.

Manifest Declaration

Add an optional webhooks array to your manifest. Each entry defines a webhook key and its operational mode:

• fire_and_forget (default): The third-party service pushes data and expects only an acknowledgment. The integration receives the event asynchronously and does not block the gateway response.
• sync: The third-party service waits for a response from your integration (e.g., for authentication challenges or application-level returns). The integration must return a command-result.data object which is relayed back to the caller.

Integration Implementation

Your integration must implement the following logic:

1. Expose Webhook URLs: Implement GET /api/integration/v1/webhook to return the available webhooks and their URLs. The core uses the user's GLADYS_OPEN_API_KEY to construct these URLs.
2. Handle Events: Use the SDK methods getWebhooks() to retrieve configuration and onWebhook(key, cb) to listen for incoming events.
3. Data Handling Doctrine: Do not treat webhook payloads as the source of truth. Webhooks can arrive out of order, duplicated, or delayed. Use the webhook strictly as a trigger to refresh data via the manufacturer's API. The polling mechanism should remain the primary source of truth.

Security and Constraints

• Payload Size: The gateway relays bodies up to 256 KB. Integration responses in sync mode are limited to 64 KB.
• Authentication: The webhook URL itself acts as the secret. The integration is responsible for verifying provider signatures (authenticity) if provided by the third party.
• Timeouts: The gateway has a hard 10s timeout. In sync mode, the integration is expected to respond within 5s.

"webhooks": [
  { "key": "events", "label": { "en": "Netatmo events" }, "mode": "fire_and_forget" },
  { "key": "callback", "label": { "en": "Subscription callback" }, "mode": "sync" }
]

Integrations can declare sub-containers (e.g., an mqtt broker) and hardware requirements (e.g., gpu).

Sub-container Lifecycle

1. Declaration: Define the sub-container in the manifest (e.g., image eclipse-mosquitto, start: "manual").
2. Hardware/Resource Access: If the integration requests hardware, the user must enable it in the Configuration screen. If disabled, GET /container will show granted: false and no volumes will be mounted.
3. Manual Start: For containers marked with start: "manual", the main integration must write configuration files (e.g., passwords) to /data/containers/<sub-container-name>/ and then call POST /container/<sub-container-name>/start.
4. Connectivity: Once started, the sub-container should be reachable via its service name (e.g., mqtt:1883) using internal DNS.
5. Supervision: The Gladys supervisor monitors the sub-container. If the sub-container is killed (docker kill), the supervisor will attempt to restart it with an exponential backoff and track the failure_count.
6. Stopping: Using POST /container/<sub-container-name>/stop will stop the container, but it will not be automatically restarted by the supervisor.
7. Cleanup: Upon uninstallation, all sub-containers, networks, and data directories must be removed.