Stratorama - Agent (Home Assistant app)

English | Français

The small Home Assistant app (formerly called an add-on) that links your Home Assistant to your Stratorama account: your home on a floor plan, live and controllable from anywhere, without exposing Home Assistant to the internet. It opens one outbound connection to Stratorama's relay and nothing else - no port forwarding, no public URL, no long-lived token handed to a browser.

[Stratorama in your browser]  --HTTPS-->  [stratorama.app relay]  <--WebSocket out--   [this app]
                                                                                            |
                                                                                            v  http://supervisor/core
                                                                                    [Home Assistant]

Open source, MIT licence. Images for amd64 and aarch64.

Also in this repository: Stratorama itself, inside Home Assistant (experimental). The app called Stratorama runs the plan in your Home Assistant, opened from its sidebar, with no account and nothing leaving your home. It needs Home Assistant OS, and the same agent is built into it. Unlike the agent, its code is not open source: its folder here holds what Home Assistant reads, and its image is built elsewhere. Its documentation, in English and French: stratorama/DOCS.md.

Requirements

• Home Assistant OS: install the Home Assistant app below (apps need the Supervisor, which Home Assistant OS provides; the unsupported Supervised install has it too).
• Home Assistant Container: apps do not run there, so run the same agent as a Docker image instead - see Home Assistant Container (Docker).
• A 64-bit machine: amd64 (x86-64) or aarch64 (Raspberry Pi 4 / 5, Home Assistant Green and Yellow, most NUC-class boxes). 32-bit ARM (armv7) is not supported.
• A Stratorama account, free: https://stratorama.app.

Install

1. Add this repository to your Home Assistant app store

The button pre-fills the dialog in your own Home Assistant. Manual path: Settings > Apps > Install app, the three-dot menu top right, Repositories, then add (before Home Assistant 2026.2: Settings > Add-ons > Add-on Store, same menu):

https://github.com/stratorama/stratorama-addon

2. Install "Stratorama - Agent"

It appears in the store under Stratorama. Press Install (the image is pulled, nothing is compiled on your machine).

3. Pair it with your Stratorama home

1. In Stratorama, open the settings menu (the three-dot menu, top right), then Home Assistant > Connection, and press Generate pairing code. The code is 8 characters and valid for 10 minutes.
2. In the app's Configuration tab, paste it into Pairing code and press Save. Leave Tunnel URL at its default. Home Assistant shows no message after a save, and none is needed: the code is saved (if the app is already running, Home Assistant asks to restart it: press Restart).
3. Back on the Info tab, Start the app. Within seconds the Connection panel shows Connected and the small Home Assistant mark in the top-right corner of your plan turns green.

The app now holds its own long-lived credential in its /data folder: restarts and Home Assistant updates reconnect on their own, and you can clear the Pairing code field.

4. Put your devices on the plan

In Stratorama's edit mode, tap a device on the plan (or the pen icon in the Elements list), then Device (on a sensor, Add reading), and pick the Home Assistant entity. Supported today: lights and LED strips (light.*), roller shutters (cover.*), power outlets and electro-valves (switch.*), and read-only sensors (sensor.*, and binary_sensor.* such as a door, motion or leak sensor). What comes next is in Using the plan.

Home Assistant Container (Docker)

Home Assistant Container has no Supervisor, so it cannot run Home Assistant apps. The same agent ships as a plain Docker image instead, ghcr.io/stratorama/stratorama-agent, for amd64 and arm64. It runs next to Home Assistant, opens no port, and does exactly what the app does: one outbound connection to the relay, and the same nine calls to Home Assistant, no others.

1. Create an access token in Home Assistant

The app is handed a token by the Supervisor; a container has to be given one.

1. Recommended: a dedicated user. In Home Assistant, Settings > People > Users > Add user, name it Stratorama and leave Administrator off: the agent needs no admin rights. Home Assistant then records what the agent does as done by that user, and deleting the user revokes it.
2. Signed in as that user (or as yourself, if you skip step 1), open your profile, Security tab, Long-lived access tokens > Create token, name it Stratorama agent, and copy it: Home Assistant shows it once.

The token never leaves your network: the agent presents it to Home Assistant and to nothing else, and the relay never sees it. The relay is not told HA_URL either: Stratorama never learns your Home Assistant's network address.

2. Generate a pairing code in Stratorama

The settings menu (the three-dot menu, top right) > Home Assistant > Connection > Generate pairing code. The code is 8 characters, valid for 10 minutes, and works once.

3. Start the agent

compose.yaml:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗