Portainer Add-On for Home Assistant (Portainer CE 2.x)

I’ve been using the Portainer add-on from the Home Assistant add-on repository for quite a while now, and using it to manage several docker hosts. I recently went to add a few Kubernetes clusters as endpoints for Portainer only to realise that the add-on was Portainer 1.x instead of 2.x (which doesn’t support Kubernetes). It doesn’t appear that there’s going to be an update to 2.x on the existing Home Assistant add-on, so I’ve created a new one based on the Portainer-CE 2.1 code.

Installation requires an additional repository to be added to Home Assistant. The repository URL is: https://github.com/MikeJMcGuire/HASSAddons. From there, the installation is pretty much the same as the original add-on. You turn off protected mode (as it needs to manipulate the docker host on which it runs), and turn on the sidebar option.

The only real difference I’ve seen so far is that the 2.x version of Portainer doesn’t have a “no authentication” option. The original 1.x add-on used this as the interface to Portainer was protected by the Home Assistant ingress option. Therefore, the 2.x version requires you to login. The default credentials are admin/portainer and you can change that password as soon as you log in the first time. I’ve kept the add-on fairly basic, but if there’s any changes/features needed they’re quite straight forward to add.

If you’re looking for changes to the add-on, call it out here in a comment, or on the repository for the add-on code.


  1. Expose Portainer ports (8000/9000 TCP) outside of the container for those that wish to have an alternative to HA ingress – done.

Update (26 May): Upgraded to Portainer 2.5.

~ Mike

17 thoughts on “Portainer Add-On for Home Assistant (Portainer CE 2.x)

  1. Hello Mike, I’m just looking at your post. The use case I’m looking for is the following. Not sure if your work will help. I have multiple docker instances running in my house, mostly on different RPIs which are doing different tasks. On each of these I’ve installed Docker/Docker Compose/Portainer. Ideally I would like to view all of them in Home Assistant. Do you think this is possible ? If so, please advice
    Thank you so much,

    1. Hi Jens – you’re best bet would be to use a single instance of Portainer (in HA) to manage other docker environments/endpoints. You should be able to find instructions on Portainer’s website about how to add other docker hosts (you basically need to configure your RPis to expose their docker port – or deploy a portainer agent to each of those hosts.

  2. Hi Mike,
    Maybe you could help me, I’m struggling with my Portainer setup.
    I have a installed Home Assistant Supervised in Docker on a Debian machine.
    And I would like to use Portainer to manage my Docker containers.
    I have installed the latest Portainer:ce and when I login, local-ip-adderss:9000 I asked to create a user, password and so on. But I don’t get the choose to select “local server” during the setup.
    Seems that the Portainer doesn’t find the local container or what is called…
    Do know what the problem could be?

    Br Fredrik

    1. Howdy – when you say you installed portainer – do you mean my addon, or the provided home assistant addon? Or have you tried to run it separately as a standalone? I’d recommend running the addon version. If you’re not, then you need to ensure you map the docker.sock file into the container.

      1. Hi Mike,

        Hoping you can help. Running Home Assistant OS in a virtual machine. So I think I need the add-on method to use portainer. I’ve installed your add-on as above, but it won’t load and is erroring out with:

        Logger: homeassistant.components.hassio
        Source: components/hassio/__init__.py:557
        Integration: Home Assistant Supervisor (documentation, issues)
        First occurred: November 28, 2021, 11:01:30 PM (79 occurrences)
        Last logged: 5:34:18 AM

        Can’t read Supervisor data: Container addon_e4641267_portainer is not running

      2. Howdy, not sure – it seems to be indicating the addon isn’t running. Is the addon running? Do the logs of the addon show anything? It might be starting and then failing due to not having protection mode disabled.

  3. I have been installing Portainer following way
    – Get the latest version of Portainer
    docker pull portainer/portainer-ce:latest
    – Create a new Docker volume for Portainer
    docker volume create portainer_data
    – Create the Portainer container
    docker run -d -p 8000:8000 -p 9000:9000 -p 9443:9443 \
    –name=portainer –restart=always \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v portainer_data:/data \

  4. Hi,
    Thanks for sharing this. I’m running into an issue of a read only files system when deploying a stack.
    I’ll admin, I’m not a portainer expert, but can you help fill in what I should replace the below with from the volumes tag in my docker-compose file?
    – ./output/:/output

  5. Hi Mike, thanks for providing this since the “official” one has been abandoned. My HA still has the 1.5.2 version of the original Portainer plugin. Do you think a simple upgrade to your plugin will work and my existing portainer configured container will be present after the upgrade?

  6. Been using this add on for a while (current version 2.13.1) but the 12 character password requirement is very annoying! Apparently 2.14.1 gives you configuration over that. When might we see it appear in HA?

  7. Hello Mike, first of all thank you for all your great work. I’m running into an issue of a read only files system when deploying a stack. Do you have any idea why?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s