Standalone Docker¶

Hanergy can run as a standalone Docker container on any machine, connecting to Home Assistant over the network via the REST API. This is the recommended approach for users running Home Assistant Core in Docker, or those who want Hanergy on a separate server.

Quick Start¶

docker run -d --name hanergy \
  -p 8099:8099 \
  -e HA_URL=http://homeassistant.local:8123 \
  -e HA_TOKEN=your_long_lived_access_token \
  -v hanergy-data:/config/addons/hanergy \
  ghcr.io/cusspvz/hanergy:latest

Then open http://your-server-ip:8099 in a browser to access the Hanergy UI.

Creating a Long-Lived Access Token¶

Hanergy needs a long-lived access token to communicate with Home Assistant.

In Home Assistant, click your user profile icon in the bottom-left of the sidebar.
Scroll down to Long-Lived Access Tokens.
Click Create Token.
Give it a name (e.g., "Hanergy") and click OK.
Copy the token immediately — it is only shown once.

Keep your token secure

The access token grants full API access to your Home Assistant instance. Do not share it or commit it to version control. Use environment variables or Docker secrets to pass it to the container.

Environment Variables¶

Variable	Required	Description
`HA_URL`	Yes	Full URL to your Home Assistant instance, including the port (e.g., `http://192.168.1.100:8123`)
`HA_TOKEN`	Yes	Long-lived access token created in the step above

Persistent Configuration¶

The -v hanergy-data:/config/addons/hanergy volume mount ensures that your configuration (energy sensors, devices, priorities, engine settings) persists across container restarts and upgrades.

Named volumes vs bind mounts

The example above uses a Docker named volume (hanergy-data). You can also use a bind mount to a specific directory on your host:

-v /path/on/host/hanergy:/config/addons/hanergy

This makes it easier to back up and inspect the configuration file directly.

Multi-Architecture Images¶

Hanergy publishes container images for three architectures:

Architecture	Image Tag	Typical Hardware
`amd64`	`ghcr.io/cusspvz/hanergy:latest`	Intel/AMD PCs, most NAS devices
`aarch64`	`ghcr.io/cusspvz/hanergy:latest`	Raspberry Pi 4/5, Apple Silicon (via Rosetta)
`armv7`	`ghcr.io/cusspvz/hanergy:latest`	Raspberry Pi 3, older ARM boards

Docker automatically pulls the correct image for your platform when using the latest tag.

Docker Compose¶

For users who prefer Docker Compose:

services:
  hanergy:
    image: ghcr.io/cusspvz/hanergy:latest
    container_name: hanergy
    restart: unless-stopped
    ports:
      - "8099:8099"
    environment:
      - HA_URL=http://homeassistant.local:8123
      - HA_TOKEN=your_long_lived_access_token
    volumes:
      - hanergy-data:/config/addons/hanergy

volumes:
  hanergy-data:

Verifying the Connection¶

After starting the container, open the Hanergy UI at http://your-server-ip:8099. On the first run, the setup wizard launches automatically.

If the connection to Home Assistant fails:

Check the container logs: docker logs hanergy
Verify that HA_URL is reachable from the Docker host.
Confirm the access token is valid by testing it with curl:
```
curl -s -H "Authorization: Bearer your_token" \
  http://homeassistant.local:8123/api/ | head -1
```
A successful response returns {"message": "API running."}.

Next Step¶

Complete the Setup Wizard