Skip to main content

Shinobi smart home integration, free and open source

Shinobi integration for Gladys Assistant

Shinobi cameras: images, motion, objects detected, mode (watch only, record), from your NVR.

View on GitHubAll integrations

Brings the cameras of a Shinobi server (the self-hosted network video recorder) into Gladys: their image, the motion Shinobi detects, the objects seen by an object detection plugin, their mode (watch only, record, disabled), and whether they are online. Shinobi's live detections start scenes, with the image of the moment, which a scene can send you. Scenes can also put a camera to record, or back to watch only.

Tested against a real Shinobi server in Docker (the official image of October 2026) with a simulated network camera and Shinobi's built-in motion detector, not yet on an installation in service with real cameras, nor with an object detection plugin: feedback welcome on GitHub or on the Gladys forum.

What you need​

  • Gladys 5.1 or later.
  • Shinobi, reachable from Gladys on its web port (8080 by default). An up-to-date Shinobi is best: live detections were tested on the Shinobi of October 2026.
  • The cameras (monitors) already added in Shinobi, with:
    • the JPEG API on (monitor settings, JPEG API section): Gladys reads the images there;
    • the detector on, with Shinobi's built-in motion detection, for Motion;
    • an object detection plugin (Tensorflow, YOLO, DeepStack…) connected to Shinobi and object detection on for the monitor, for Object detected. Shinobi's built-in detector only sees motion.
  • An API key of your Shinobi account. In Shinobi, click your user name (top left), then API, and add a key: IP 0.0.0.0 (or the address of Gladys), with the permissions to see and control monitors, see snapshots, and Can Authenticate Websocket (live detections).
  • The group key of your account: in Shinobi, your user name, then Settings (Group Key).

Installation​

  1. In Gladys, open Integrations, find Shinobi and install it.
  2. In its Configuration tab, fill in:
    • Shinobi address: the address of the computer running Shinobi, e.g. 192.168.1.20. Without a port, 8080 is used; add :port if it was changed, or https:// behind a reverse proxy.
    • API key and Group key: as above.
    • Image refresh: how often each camera image is sent to Gladys (from 10 seconds to 15 minutes, 1 minute by default). A detection also sends one at once.
    • End of a detection: Shinobi sends each detection, never its end. Motion and Object detected go back to 0 after this delay without a new detection (30 seconds by default). The triggers follow the same delay: a detection fires a scene again once this delay has passed.
    • Language of the names: the language of the feature names given when a camera is added.
  3. Save, then open the Discovery tab: one device per camera. Add the ones you want.
  4. Check the connection shows what the integration reads: whether live detections are received, each camera, its mode, whether it is online, and what is missing (JPEG API off, no detector).

The Gladys devices​

Each Shinobi monitor becomes a Gladys camera, named as in Shinobi, with:

FeatureWhat it is
ImageThe camera image, sent at the chosen pace and at once on a detection.
Motion1 when Shinobi's motion detector saw motion a moment ago, else 0.
Object detected1 when an object plugin saw an object a moment ago, else 0. If the monitor has it.
ModeWatch only, Record, Idle or Disabled. A list: the dashboard can change it.

Whether the stream comes in is shown by the device itself: a camera whose stream is lost shows as unreachable in Gladys (and fires Shinobi: camera offline). Mode is a list on purpose, never a switch a voice assistant would flip by mistake. A large Shinobi snapshot is made smaller in the integration to fit Gladys (150 KB per image).

Dashboard widget​

Shinobi camera shows the image of a camera, motion, the objects seen a moment ago (e.g. "person, car"), the mode and online, and two buttons: Record (or Watch only while it records) and New image.

Scenes​

Triggers​

  • Shinobi: motion detected: Shinobi's motion detector sees motion on a camera. Filters: the camera (empty = all) and the region (a region name drawn in Shinobi, empty = all). Variables: the camera name, the region (empty for the whole image) and the confidence in % (the share of the image that changed). The image of the moment is sent to Gladys first.
  • Shinobi: object detected: an object detection plugin sees an object. Filters: the camera and the object (label, as the plugin names it: person, car, dog…). Variables: the camera name, the object and the confidence in %. One event per object seen.
  • Shinobi: camera offline: a camera watching or recording loses its stream for 30 seconds, or Shinobi itself stops answering. Not fired for a camera disabled or idle in Shinobi, nor for the restart that follows a mode change.

Actions​

  • Shinobi: record or watch only: Record puts a camera to continuous recording, Watch only puts it back to watch only (Shinobi keeps recording on detections if the monitor is set to). The API key needs the permission to control monitors.

The core's Send a camera image action sends the last image of a camera: right after Shinobi: motion detected or Shinobi: object detected, it is the image of that moment.

Scene ideas​

  • Someone at the door: Shinobi: object detected, camera "Entrance", object person → Send a camera image of that camera to your phone, with {{triggerEvent.data.score}} % in the text.
  • Motion in the driveway at night: Shinobi: motion detected, region driveway → switch the outdoor light on for five minutes.
  • Record while away: everybody leaves home → Shinobi: record or watch only, Record, on the hall camera; Watch only when someone is back.
  • Camera lost: Shinobi: camera offline → send a message with the camera name.

Troubleshooting​

  • "Shinobi does not answer at this address": open http://<address>:8080 in a browser. Check the port and that no firewall blocks Gladys.
  • "Something answers, but not like Shinobi": the address or the port leads to another service. Enter the address of Shinobi, without a page path (a path is kept behind a reverse proxy).
  • "Shinobi refuses the API key or the group key": copy both again from Shinobi; check the IP allowed for the key (0.0.0.0 for any).
  • "No live detections: give the API key the permission Can Authenticate Websocket": edit the key in Shinobi (user name → API). Without it, the states are read once a minute and no detection reaches Gladys.
  • "JPEG API off": turn the JPEG API on in the monitor settings; without it Shinobi only has a placeholder image.
  • Motion stays at 0: the detector of the monitor is off, or its sensitivity too high for what moves (Shinobi's detector settings). Shinobi's own event list shows whether it detects.
  • A reverse proxy: it must let WebSockets through on /socket.io/.
  • More details: the integration logs (Integrations → Shinobi → Logs); set LOG_LEVEL to debug to see each request (never with the key).

Limits​

  • No live video: Gladys shows images, sent at the chosen pace (Gladys keeps 12 images a minute per camera at most). The live stream and recordings are watched in Shinobi.
  • Shinobi sends detections, not their end: Motion and Object detected stay on for the chosen delay after the last one.
  • Regions and labels are filtered as written in Shinobi: the scene filters only compare text.
  • Disabling a camera is done from the Mode list or in Shinobi, not by a scene action.
  • Past recordings, events history, PTZ and timelapses are not covered.
  • Live detections need a recent Shinobi: the 2021 image of Docker Hub does not send them (the states are then read every minute).
  • One Shinobi group (one group key) per integration.
  • Developed without the hardware: feedback welcome. Tested with the official Shinobi image in Docker and a simulated camera; the objects were simulated through Shinobi's own API, without a plugin.

This integration is not affiliated with Shinobi Systems.

Configuration settings​

These are the settings Shinobi asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Your Shinobi serversectionNoShinobi, the self-hosted video recorder. Create an API key in Shinobi (your user name, then API), enter it with the group key, then open the Discovery tab: one device per camera.
Shinobi addressstringYesWithout a port, 8080 is used. Add https:// for a reverse proxy.
API keysecretYesGive it the permissions to see and control monitors, see snapshots, and "Can Authenticate Websocket" for live detections.
Group keystringYesShown in Shinobi under your user name, then Settings (Group Key).
Image refreshselectNoHow often each camera image is sent to Gladys. A detection also sends one at once.
End of a detectionselectNoShinobi sends each detection, never its end: motion goes back to none after this delay without a new one.
Language of the namesselectNoNames given to the features when a camera is added (Motion, Mode…).

How to install Shinobi in Gladys​

  1. In Gladys, open Integrations: Shinobi appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-shinobi:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-shinobi.

Shinobi requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Shinobi is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on