# Otonomo — install guide From zero to live data, end to end. About 30 minutes if your hardware is on the network and a Linux box is ready. This document is the canonical walkthrough for new customers. If something doesn't match what you see on screen, the live site at [app.otonomo.be](https://app.otonomo.be) wins — this is a snapshot in time. --- ## What you're installing Otonomo is a home-energy intelligence platform. You install a small agent on a Linux box on your home network. The agent talks to your hardware (boiler, solar inverter, battery, EV charger, sensors) using open protocols, streams telemetry to our cloud, and — when you're ready — receives optimization commands back to schedule charging, hot water, and heating against electricity prices and solar forecast. - **Free during your trial** (observe mode). Drivers run, data flows, cloud dashboard shows everything. No commands are sent back to your hardware. - **€3 / month when you flip to active**, opt-in per capability. You choose what we optimize (battery dispatch, EV charging, hot water, etc.) and can override anything in your local UI or in Home Assistant at any time. - **Your data, your call.** One-click toggle in the local UI stops the cloud uplink without uninstalling. Local dashboard + Home Assistant keep working. Request full data deletion any time from the cloud dashboard. --- ## Before you start You'll need: ### Hardware - A Linux box on your home network — Raspberry Pi 4, Pi Zero 2 W, NUC, mini-PC, or an old laptop. Minimum **512 MB RAM, ~2 GB disk**, always-on. - At least one piece of supported hardware: PV inverter, heat pump, gas boiler, EV charger, smart meter, or temperature sensor. See `docs/drivers/` for the per-vendor list. - Network connectivity from the Linux box to: - Your hardware (LAN — for Modbus/local-MQTT/RS485 drivers) - `app.otonomo.be` over HTTPS (port 443) and MQTT/TLS (port 8883) ### Software - A reasonably current Linux distro: - **Debian 12** / **Ubuntu 22.04+** / **Raspberry Pi OS Bookworm** — works with the one-liner installer - Fedora / Arch / NixOS — works with a 4-step manual install (see `/onboarding/help` once you're signed up) - `sudo` access (the installer needs root for systemd + system packages) - Python 3.11 or later (the installer handles this on supported distros) ### Time - 5 minutes to sign up - ~90 seconds for the one-liner to run - 5 minutes per driver to configure - Total for a typical install: **20–30 minutes** ### Decisions You'll be asked these during install — think about them now: | Decision | Options | Notes | |---|---|---| | **Local UI mode** | Full / Config-only / None | Pick "Full" if you want the local dashboard. Pick "Config-only" if you'll use Home Assistant for charts (the drivers wizard still works). Pick "None" if you want a pure background agent. | | **First driver(s)** | Any of the catalog | Have IPs ready for Modbus devices. Have account credentials ready for cloud-API drivers (Easee, Aquarea, etc.). | You can change all of this later — re-running the one-liner with a different `OTONOMO_LOCAL_UI=` value is idempotent. > **Cloud VPS users:** the agent runs on any Linux. But if any of your > hardware uses Modbus / USB-serial / local MQTT, the agent has to be on the > same network — you can't reach a USB cable from a Hetzner box. Cloud VPS > only works if every device you have is reachable through a vendor cloud > API (Aquarea Smart Cloud, Easee Cloud, etc.). --- ## Step 1 — Sign up 1. Visit [app.otonomo.be/get-started](https://app.otonomo.be/get-started). 2. Click **Create your account**. 3. Enter email + a strong password. Verify your email when the confirmation message arrives (usually within a minute — check spam if not). > **Invite-only?** The founding-100 batch is invite-gated by default. If > you hit the "invite required" page, click **Join the waitlist** and > drop your email + the hardware you have. We're processing waitlist > entries in roughly the order they arrive, prioritising hardware we > already test against. --- ## Step 2 — Pick your install mode After signup you land on `/onboarding`. The page shows three tiles: - **Full** *(default)* — local dashboard with charts + drivers wizard. About 1.5 MB extra RAM. Recommended if you want a local pane of glass during the trial. - **Config only** — drivers wizard at port 8080, no local charts. Picks this if you'll use Home Assistant or the cloud dashboard for visualisation. - **None** — no local web UI at all. Pure background agent. For power users who'll manage everything from the cloud or via SSH. Click the tile you want. The installer one-liner under it updates automatically. > Don't agonise. **Full** is a safe default and downgrading later takes 60 > seconds — re-run the same one-liner with `OTONOMO_LOCAL_UI=config` or > `OTONOMO_LOCAL_UI=off`. Your enrollment and configured drivers all survive. --- ## Step 3 — Run the one-liner The `/onboarding` page shows a command like: ```bash curl -fsSL https://app.otonomo.be/static/install.sh \ | OTONOMO_TOKEN=ent_xxxxxxxxxxxx OTONOMO_BASE=https://app.otonomo.be bash ``` (Yours will have a real token and possibly an `OTONOMO_LOCAL_UI=` env var based on the mode you picked.) SSH into your Linux box as a user with `sudo`, paste the command, run it. The installer takes ~90 seconds and prints what it's doing: ``` ▸ preflight ▸ installing system packages ▸ creating filesystem layout ▸ building Python venv (this is the slow step ~60-90s) ▸ fetching otonomo agent payload ▸ activating with cloud ▸ configuring local mosquitto ▸ installing privacy-toggle helper + sudoers rule ▸ installing systemd units ▸ smoke test ✓ install complete Box-id hems-900037 Local UI mode full Local dashboard http://192.168.x.x:8080/ Cloud dashboard https://app.otonomo.be/?box=hems-900037 ``` > **The installer reads the script before piping to bash.** It's about 250 > lines and entirely visible at `app.otonomo.be/static/install.sh` — no > obfuscation, no minification. Read it first if you want to. After the script finishes, your `/onboarding` page in the browser flips from "Waiting for first contact from your box…" to **"✓ Your box is online"**. --- ## Step 4 — Add your first driver Now your agent is running but it doesn't know about any hardware yet. Open the drivers wizard: **In Full or Config mode:** `http://:8080/drivers` **In None mode:** edit `/etc/otonomo/site_manifest.yaml` by hand (see the per-driver guide for the exact YAML); then `sudo systemctl kill -s SIGHUP otonomo-publisher`. The drivers page groups our catalog by hardware type — PV Inverter, Battery, Heat Pump, Gas Boiler, EV Charger, Grid Meter, Temperature Sensor. Each driver shows a stability pill (stable / beta / experimental) and the vendors it covers. ### For each driver you want to add: 1. Find it in the catalog. Click **Install** — Otonomo pip-installs the driver in the local venv (~5 seconds). 2. Click **Add instance** — fills in a form with the driver's config fields. Typical fields: - **IP address** of the device (for Modbus / local-API drivers) - **Port** (driver-specific defaults work for ~95% of installs) - **Credentials** (for cloud-API drivers like Easee or Aquarea) 3. Click **Create instance**. Within 30 seconds your local dashboard's relevant page lights up. We've published detailed setup guides for the five most-common drivers (`docs/drivers/`): - [Vaillant gas boilers](drivers/vaillant_ebus.md) — needs eBUS adapter - [SolarEdge inverters](drivers/solaredge_modbus.md) — needs Modbus TCP enabled - [Daikin air-to-air heat pumps](drivers/daikin_local.md) — needs BRP WiFi adapter - [Shelly H&T sensors](drivers/shelly_rpc.md) — point them at your box's mosquitto - [Easee EV chargers](drivers/easee_api.md) — cloud-API; needs Easee account creds Other drivers — Aurora, Huawei, HomeWizard P1, go-e, Marstek, Enphase, LG Therma V, Panasonic Aquarea, WLBox2 — work the same way; per-driver guides ship as they reach stable. --- ## Step 5 — Verify and explore You should now have data flowing. Check both places it should be visible: ### Locally (Full mode only) `http://:8080/` You should see cards: PV Now, Battery, Hot water tank, Grid, EV — whichever match the drivers you configured. Click any device tab to see 6 hours of trailing data on hand-rolled SVG sparklines. > Local data is **in-memory only, 6 hours, no disk persistence.** Restart > the agent and the buffer empties. This is by design — the cloud is the > historical source of truth, the local UI is a live diagnostic. ### Cloud [app.otonomo.be/?box=hems-XXXXXX](https://app.otonomo.be/) (the URL is printed at the end of the install). Same metrics, plus weeks of history, money page, finance dashboard, control overrides. The full `/pro` surface. ### Home Assistant (optional) If you run HA, point its MQTT integration at `:1883` (anon, no TLS — LAN-only mosquitto). Every metric your drivers publish becomes an MQTT topic at `hems//telemetry/#`. HA auto-creates entities. A one-click HACS integration ships ~Q3 2026 — for now, the manual MQTT setup takes about 2 minutes. See [`installer/ha_integration/README.md`](../installer/ha_integration/README.md). --- ## Step 6 — When you're ready, flip to active You're in **observe mode** by default. Data flows up, but nothing flows down. Your hardware does what it was doing before Otonomo was installed. When you're satisfied with what you see and want optimization, visit [app.otonomo.be/account/control](https://app.otonomo.be/account/control) and flip the per-capability toggles you care about: - ☑ Battery dispatch — schedule charging from grid at cheap hours; discharge during peaks - ☑ EV charging — slot the car into off-peak or PV-surplus windows - ☑ Hot water (DHW) — pre-charge the tank ahead of expensive evenings - ☐ Heating setpoints — weather-compensated flow temp control Each capability you check is €3/month and we measure the savings on your meter. If the saving isn't at least 10× the price, cancel. Every toggle has a "manual override for 2 hours" button so you can intervene any time without fully turning the feature off. > **What counts as savings?** The cloud dashboard's `/pro/finance` page > shows the cumulative euros saved month-by-month, broken down per > capability. The methodology is documented at > `docs/otonomo_lift_methodology_2026_05_04.md` — we credit only the > *automation delta* over what your stock hardware would have done > passively. No padded numbers. --- ## Privacy and control ### Pause cloud uplink any time Open `http://:8080/settings` and click **Disable cloud uplink**. The drivers, local dashboard, and Home Assistant stream keep running. Only the cloud uplink stops. Click again to resume — telemetry catches up within about 5 seconds. Headless installs (or scripted workflows): ```bash sudo sed -i "s/^CLOUD_TELEMETRY_ENABLED=.*/CLOUD_TELEMETRY_ENABLED='false'/" /etc/otonomo/env sudo systemctl kill -s SIGHUP otonomo-publisher ``` ### Delete data already on our cloud Pausing uplink stops new data going out, but doesn't remove what's already on our side. Request deletion from [app.otonomo.be/account/data](https://app.otonomo.be/account/data) — we process within 30 days (typically within 7). ### Uninstall completely ```bash sudo bash /opt/otonomo/uninstall.sh ``` Removes our three services, our config under `/etc/otonomo/`, and our mosquitto conf snippet. Leaves mosquitto itself (it might be yours). Your cloud data is untouched — use the deletion-request link above to remove that separately. --- ## Help and support | Need | Where | |---|---| | Troubleshoot install errors | [app.otonomo.be/onboarding/help](https://app.otonomo.be/onboarding/help) — 9-item FAQ | | Per-driver setup | [`docs/drivers/`](drivers/) in this repo | | Install on Fedora / Arch / NixOS | Email support; we'll walk you through | | Anything else | | When emailing for help, include: ```bash sudo journalctl -u otonomo-publisher --no-pager | tail -50 ``` …and your **box-id** (visible at `http://:8080/` or on the cloud dashboard). That's usually enough for us to diagnose in one round-trip. --- ## Reference — files and services on your box If you want to know what's where: | Path | What | |---|---| | `/opt/otonomo/venv/` | Python virtualenv with the SDK + drivers | | `/opt/otonomo/local_ui/` | The :8080 web UI | | `/opt/otonomo/bin/privacy_apply.py` | Sudoer-blessed helper for the privacy toggle | | `/etc/otonomo/env` | Box-id, MQTT creds, cloud uplink flag (root-only readable) | | `/etc/otonomo/site_manifest.yaml` | Which drivers are configured | | `/etc/otonomo/ca_chain.pem` | Cloud broker CA cert | | `/etc/sudoers.d/otonomo-privacy` | Allows the otonomo user to flip the cloud toggle | | `/etc/systemd/system/otonomo-*.service` | Three systemd units | | `journalctl -u otonomo-publisher -f` | Live publisher log | | `journalctl -u otonomo-cmd-subscriber -f` | Live cloud → driver command log | | `journalctl -u otonomo-local-ui -f` | Live local UI log | If anything looks off, those three `journalctl` invocations tell you what's actually happening. --- ## What this guide doesn't cover - **Operator-side workflows** (waitlist sweep, invite issuance, deletion approval) — see [`operator_runbook_byoh.md`](operator_runbook_byoh.md). - **Engineering deep-dive** on install modes, mode switching, component interactions — see [`otonomo_install_modes_detailed.md`](otonomo_install_modes_detailed.md). - **Driver protocols and capabilities** — see [`hems_open_driver_sdk_2026_05_13.md`](hems_open_driver_sdk_2026_05_13.md) and per-driver guides in [`drivers/`](drivers/). - **Architecture / charter rules / thin-edge design** — the architecture doc lives at `docs/hems_thin_edge_pivot_2026_04_22.md` for anyone who wants to understand the cloud-authoritative model. --- **Done.** If you walked through to here and your dashboard is showing live data, you're in. The agent stays running across reboots; nothing else needs to be done unless you want to add more drivers or flip to active mode. If you got stuck anywhere, write us at with what you saw — that's how this guide gets clearer for the next person.