Setup guides → Enphase

Enphase

Enphase is the system I run at home, and it is the one Sunplug reads best. The IQ Gateway sits on your network and answers in about a second — no cloud, no rate limit, no subscription.

What you need

• An IQ Gateway (an Envoy, on older systems) on your home network
• A machine that stays switched on — a NAS, a Raspberry Pi, a Home Assistant box
• Your Enlighten login, used once

Why it runs on your network

Enphase does have a cloud API, and Sunplug does not use it. Two reasons, both worth knowing before someone suggests otherwise:

It serves fifteen-minute averages, and the free developer plan allows about a thousand calls a month — roughly one reading every forty-five minutes. You cannot follow a moving cloud edge with that. The paid tiers work out at around thirty to forty dollars per site per month, which is more than this whole product can sensibly cost.

Enphase's own API terms also say it is not for consumer-facing applications. Reading your own gateway, on your own network, is not covered by any of that.

This is why Sunplug supports Enphase at all. ChargeHQ never did — their documentation cited "technical and commercial constraints", which reads exactly like the two paragraphs above.

Installing

Docker

On any always-on machine on the same network as the gateway — a NAS, a NUC, a Raspberry Pi. The image is published for both x86 and ARM.

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 from any browser on your home network — your phone will do.

The page scans your network, finds the gateway and reads its serial number for you, asks for your Enlighten login, and then asks for the six-character pairing code from the app. After that it starts with the machine and looks after itself. No terminal at any point.

--network host is not optional. The agent sweeps your local subnet to find the gateway, and a container on a bridge network cannot see it. On a NAS whose Docker interface will not let you set that, use its Compose or Projects feature instead — there is a compose.yml in the repository that sets it for you.

Home Assistant

If you already run Home Assistant, this is two clicks rather than a terminal.

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

You will need the six-character code from Sunplug: Settings → Solar system → Sunplug Agent.

Without Docker

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

About that password

Enphase will not issue a gateway token without an Enlighten login. The agent uses yours for exactly one request, receives a token scoped to your gateway and valid for about a year, and stores that. The password itself is never written to disk and never leaves your network — it does not reach Sunplug's servers at all.

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. In the app, the freshness indicator on the dashboard should settle to a few seconds.

When it does not work

Nothing found on the network

The machine running the agent is probably on a different network segment from the gateway — guest Wi-Fi and IoT VLANs are the usual culprits. You can skip the search: sunplug-agent setup --host 192.168.1.50, with your gateway's address.

The gateway rejects the token

Tokens last about a year and the agent renews them a month before expiry. If one is rejected sooner, it re-mints automatically. Repeated failures usually mean the Enlighten password changed.

House consumption looks wrong, or is missing

Consumption needs the CT clamps fitted around your supply. Plenty of Enphase installs have production monitoring only. Without them Sunplug can see what your panels make but not what is spare — pair a Shelly meter at the supply point and it works out the rest.

Charging never starts on a sunny day

Almost always the grid sign. Export must read as a negative number. If the dashboard's flow diagram shows power going the wrong way between your house and the grid, that is the thing to fix first.

Stuck? Email me — include the log output and I will tell you what it means.