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 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:

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.
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:

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://<your-box-ip>: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:
3. IP address of the device (for Modbus / local-API drivers)
4. Port (driver-specific defaults work for ~95% of installs)
5. Credentials (for cloud-API drivers like Easee or Aquarea)
6. 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 — needs eBUS adapter
• SolarEdge inverters — needs Modbus TCP enabled
• Daikin air-to-air heat pumps — needs BRP WiFi adapter
• Shelly H&T sensors — point them at your box's mosquitto
• Easee EV chargers — 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://<your-box-ip>: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 (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 <your-box-ip>:1883 (anon, no TLS — LAN-only mosquitto). Every metric your drivers publish becomes an MQTT topic at hems/<box-id>/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.

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 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://<your-box-ip>: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):

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 — we process within 30 days (typically within 7).

Uninstall completely

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

When emailing for help, include:

sudo journalctl -u otonomo-publisher --no-pager | tail -50

…and your box-id (visible at http://<box-ip>: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:

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.
• Engineering deep-dive on install modes, mode switching, component interactions — see otonomo_install_modes_detailed.md.
• Driver protocols and capabilities — see hems_open_driver_sdk_2026_05_13.md and per-driver guides in 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 support@otonomo.be with what you saw — that's how this guide gets clearer for the next person.