Setup guides → Sunplug Agent

Sunplug Agent

A small program that runs on your own network and reads your equipment directly, every thirty seconds. Optional — Sunplug works from your manufacturer's cloud too — but it is the difference between following the sun and reacting to it long after it moved.

Proven in the field

Running the author's own house talking to an Enphase IQ Gateway every thirty seconds.

How freshEvery few seconds

Needs a port openedNo — outbound only

Runs onx86 and ARM

Setup timeFive minutes

Why bother

Cloud APIs cannot be fresher than the inverter's own upload schedule, and for most brands that is five minutes — fifteen for SolarEdge. A cloud passes, your surplus halves, and the cloud API will tell you about it in four minutes' time.

The agent asks the hardware. No rate limits, no subscription, no vendor terms, and no credentials for your equipment leaving your house.

What it works with

EnphaseIQ Gateway — production, grid, load, battery

FroniusInverter's own API — needs a Smart Meter for load

ShellyEM and Pro 3EM, as a grid meter

Docker

On anything that stays switched on and sits on the same network as your inverter. The image is published for x86 and ARM, so a Raspberry Pi or a NAS is fine.

Docker Hubsunplugapp/sunplug-agent

GitHubghcr.io/sunplug/sunplug-agent

docker run -d --name sunplug-agent --network host \
  -v sunplug-agent:/data --restart unless-stopped \
  sunplugapp/sunplug-agent:latest

Then open http://<that machine>:8787 in any browser on your home network — your phone is fine — and follow the page. It looks for your inverter, shows you what it found, and asks for the six-character code from the app. That is the whole setup.

There is no second command to run. The agent serves its own setup page and starts reading the moment it is paired; the same address afterwards shows what it is reading. If you would rather use a terminal, you still can: docker exec -it sunplug-agent sunplug-agent setup.

Two things the run command sets that a NAS "search and install" button will not. --network host, without which the agent cannot see your subnet to find anything. And a volume on /data, without which the pairing is lost every time the container updates.

Compose

If your NAS has a Compose or Projects feature — Synology, QNAP and UGREEN all do — that is the easier route, and it sets both of the above for you.

services:
  agent:
    image: sunplugapp/sunplug-agent:latest
    network_mode: host
    restart: unless-stopped
    volumes:
      - agent_data:/data

volumes:
  agent_data:

Home Assistant

Settings → Add-ons → Add-on store → ⋮ → Repositories
Add https://github.com/sunplug/sunplug
Install Sunplug agent and start it
Press Open Web UI and follow the page

The setup page appears as a panel inside Home Assistant, so nothing leaves the interface you are already in. If you prefer, the Configuration tab still accepts a pairing code and the rest of the answers directly.

Without Docker

pip install "git+https://github.com/sunplug/sunplug.git#subdirectory=agent"
sunplug-agent run

Then open http://localhost:8787, or the machine's address from another device.

Pairing

There is no API key to copy around. In the app, Settings → Equipment → Add agent shows a six-character code; the agent asks for it once and receives its own token in exchange.

The code is single use and expires after fifteen minutes — it is a claim ticket, not a credential. Each machine's token can be revoked on its own from Settings, which also shows when each agent last reported.

Commands

sunplug-agent run        serve the setup page, then read and push, forever
sunplug-agent ui         the setup page on its own
sunplug-agent discover   list equipment on this network and stop
sunplug-agent setup      find equipment, pair, save — the terminal version

run is the default and what the container does. The page is on port 8787; set UI_PORT=0 to turn it off.

Updating

Sunplug tells you in the app when a newer agent is out, because nothing updates itself — a container keeps running whatever image it started with, however old.

A NAS

Most NAS Docker interfaces hide this behind a re-pull rather than an update button, which is why it looks like there is no option:

UGREEN (UGOS) — Docker → Project → your project → ⋯ → Settings → Compose configuration → Redeploy, tick Pull the latest image, then Deploy
Synology — Container Manager → Overview shows when an update is waiting; for a project, Project → Action → Build, which re-pulls and recreates
QNAP — Container Station → Images → Pull (sunplugapp/sunplug-agent, tag latest), then Overview → Edit Application → Apply without changing anything; it rebuilds what changed
Asustor — Portainer or Docker Engine → Images → Pull, then recreate the container
TrueNAS SCALE — Apps → the app → Update, or edit and save to re-pull a custom app
Unraid — Docker tab → Check for Updates → apply update
Portainer (any NAS) — open the container → Re-pull image → Recreate

The common thread: almost none of them call it "update". Look for re-pull, rebuild or redeploy — they all mean fetch the newer image and start the container again from it.

Docker or Compose

docker compose pull && docker compose up -d

Or, without Compose:

docker pull sunplugapp/sunplug-agent:latest
docker rm -f sunplug-agent
docker run -d --name sunplug-agent --network host \
  -v sunplug-agent:/data --restart unless-stopped \
  sunplugapp/sunplug-agent:latest

The volume on /data is what makes this safe to do: the pairing lives there, so a replaced container comes back already paired and carries on reading. Nothing to set up again.

Home Assistant

Settings → Add-ons → Sunplug agent → Update, when one is offered.

Checking it works

docker logs -f sunplug-agent

A line every thirty seconds like pv=2.62kW grid=-0.31kW load=2.31kW soc=0.47. On the dashboard, the freshness indicator should settle to a few seconds.

When it does not work

Nothing found on the network

Usually the machine is on a different segment from the inverter — guest Wi-Fi and IoT VLANs are the common culprits. Skip the search with sunplug-agent setup --host 192.168.1.50.

It says it is not set up

run refuses to start until setup has been through, rather than looping on a missing token. Run the setup command above.

"This agent's access was revoked"

Someone removed it from Settings → Equipment. Pair it again with a fresh code.

The dashboard still shows cloud data

Once an agent is feeding, Sunplug stops polling your manufacturer's cloud — the local reading is always better, and mixing the two would interleave two pictures of the same house. The equipment page says so when it happens.

What leaves your network

Site power readings and nothing else: production, grid, house load, battery power and charge level. Your inverter's credentials stay on the machine, and the connection is outbound only — there is no port to open and nothing of yours is reachable from the internet.

If the agent cannot reach your hardware

Some setups have no local API at all — an inverter that only talks to its own cloud, or a meter behind a bridge the agent does not speak. You are not turned away for owning the wrong brand: send the readings yourself, from a script, Node-RED, or anything that can make an HTTP request. Sending your own readings has the format and a working example.

Stuck? Email me with the log output.