2025.10.1
Home ▸ Integrations ▸

Portainer

The Portainer integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] is used as an interface to the Portainer API. Portainer is a lightweight management UI that allows you to easily manage your Docker containers, images, networks, and volumes. It works on every Docker host or Swarm cluster.

The Portainer API provides a way to manage Docker containers, images, networks, and volumes. It allows you to interact programmatically with your Docker host or Swarm cluster.

Prerequisites

Before you can configure Portainer within Home Assistant, you need a few things:

  • have Portainer installed and a user with administrator rights on Portainer.
  • An access token.

Create a Portainer Access Token by following these steps:

  1. Log in to your Portainer instance.
  2. To create an access token, follow the steps in the Portainer documentation.
  3. Copy the generated Access Token and store it somewhere safe, you will need it in the next steps.

Configuration

To add the Portainer integration to your Home Assistant instance, use this My button:

Manual configuration steps

If the above My button doesn’t work, you can also perform the following steps manually:

  • Browse to your Home Assistant instance.

  • Go to Settings > Devices & Services.

  • In the bottom right corner, select the Add Integration button.

  • From the list, select Portainer.

  • Follow the instructions on screen to complete the setup.

Supported functionality

Note

This integration is currently being actively developed and tested. More platforms and features will be added in the future.

There is currently support for the following device types within Home Assistant:

  • Binary sensor - for monitoring the status of Portainer services.

Data updates

The integration normally updates every 60 seconds. For more detailed steps on how to define a custom polling interval, follow the procedure below.

Defining a custom polling interval

If you want to define a specific interval at which your device is being polled for data, you can disable the default polling interval and create your own polling automation.

To add the automation:

  1. Go to Settings > Devices & services, and select your integration.
  2. On the integration entry, select the .
    • Then, select System options and toggle the button to disable polling. Disable polling for updates
  3. To define your custom polling interval, create an automation.
    • Go to Settings > Automations & scenes and create a new automation.
    • Define any trigger and condition you like.
    • Select Add action, then, select Other actions.
    • Select Perform action, and from the list, select the homeassistant.update_entity action.
    • Choose your targets by selecting the Choose area, Choose device, Choose entity, or Choose label buttons. Update entity
  4. Save your new automation to poll for data.

Removing the integration

This integration follows standard integration removal.

To remove an integration instance from Home Assistant

  1. Go to Settings > Devices & services and select the integration card.
  2. From the list of devices, select the integration instance you want to remove.
  3. Next to the entry, select the three dots menu. Then, select Delete.

After removing the integration, consider deleting the Portainer access token.