Portainer Agent Manage Remote Docker environment

Portainer is a great tool I use in the home lab environment and production for managing Docker container environments, Kubernetes, and installing containerized applications. It makes the Docker user experience much more seamless, allowing you to manage Docker nodes effectively using the Docker API. In case you didn’t know, Portainer also has a Portainer agent that allows you to set up a manager node on a specific Portainer instance to manage your other Docker nodes. Let’s see how this works.

What is Portainer?

In case you have not heard about Portainer, it is a solution that allows you to manage Docker, Docker Swarm, Nomad, and Kubernetes clusters from a centralized console. It allows having a better Docker user experience compared to working with Docker from the command line

Portainer touts a universal container management platform, allowing you to manage your containers in standalone or cluster mode, on-premises, cloud, edge, IoT, etc.

Portainer capabilities

Portainer allows you to manage many aspects of your environment, including:

  • Docker volumes found in var lib docker volumes, and all these resources, including all the volumes

  • Bind mounted volumes

  • Environment variables

  • Specific node configuration

  • Overlay network configuration

  • Port configuration

  • Containers

  • Networks including IP configuration

  • Adds services to configuration

  • Managing Swarm

What is the Portainer agent?

Portainer has a solution that is called the Portainer Agent. It is a Portainer agent container that you use to spin up on remote nodes, allowing you to manage the node from a single Portainer instance in your environment.

No need to spin up additional Portainer servers

This eliminates the need to spin multiple Portainer server nodes to manage each container host with agents using an existing Portainer instance which can be your first Portainer instance.

The user interactions with container resources, including containers themselves, networks, volumes, and images, are limited to those available on the node targeted by the Docker API request.

Docker Swarm mode

You can also operate in Docker Swarm mode to manage swarm clusters. What is Docker Swarm mode? Docker swarm mode introduces the clustering Docker nodes in a Swarm cluster. What are cluster-aware resources? Cluster aware means you can query for a list of services and inspect tasks inside cluster nodes as long as you are executing on the docker swarm manager node.

Like the better experience managing standalone Docker nodes, the Portainer agent brings a better experience managing swarm clusters as it adds the same familiar GUI management found in managing other environments with Portainer.


The agent aims to allow previously node-specific resources to be cluster-aware resources while keeping the Docker API request format. It allows executing one Docker API taskto retrieve resources from each node.

Overcomes limitations

The Portainer agent solves an issue with a Docker API limitation when using Docker APIs to manage a Docker environment.

Works as a Proxy

The Portainer agent works as a proxy, introducing a header called X portaineragent target header, which has the name of any node in the cluster. For security reasons, each HTTP request made from the Portainer instance to the agent, it generates a signature using a private key. The Portainer instance encodes its public key in the header of the request.

For each HTTP request received from the agent, the agent checks the headers are available in the request. If not it returns a 403 error and triggers the signature verification request.

Environments you can connect

What types of environments can you connect with Portainer? Note the following:

  • Docker standalone

  • Docker Swarm

  • Kubernetes

  • ACI

  • Nomad

  • KaaS

Install the Portainer Agent

Let’s look at installing the Portainer agent on a remote Docker host. On your remote Docker host, to install the Portainer agent, run the following command:

docker run -d -p 9001:9001 –name portainer_agent –restart=always -v /var/run/docker.sock:/var/run/docker.sock -v /var/lib/docker/volumes:/var/lib/docker/volumes portainer/agent:latest

Once you install the Portainer agent on the remote Docker host, you can add the host to your main Portainer instance.

Once the host is added, you will see the new host in the right-hand pane.

Navigating back out to the environments menu, you will see the new environment added to the Portainer instance. Here, you can select the new environment and start managing the remote Docker cluster using your main Portainer instance and any node inside the remote cluster. It allows you to easily manage global placement of resources when configured.

Tuning Portainer Agent behavior

You can tweak the behavior of the Portainer agent with mandatory and optional variables, including the example below:

  • AGENT_SECRET – shared secret used in the signature verification process

  • AGENT_HOST – address of the agent API

  • AGENT_PORT – Port which the agent API will be exposed

You can read the official documentation here: agent/ at develop ยท portainer/agent ยท GitHub

Portainer agent FAQs

What is Portainer? Portainer is a container management solution that allows managing Docker, Docker Swarm, Kubernetes, Nomad, and other environments as part of the solution. You can use the Portainer agent to manage remote nodes. The Portainer community edition is free and open source, so it is freely available in your environment. The Business Edition offers many great features for enterprise organizations.

What is the Portainer agent? With the Portainer agent you can install the Portainer agent on a remote node and then manage the node with the centralized Portainer dashboard. The remote Portainer agent can be installed on Docker, Swarm, Kubernetes, Nomad, and other environments, and it helps to overcome limitations with native Docker API management.

How is the Portainer agent installed? The Portainer agent runs as a container on the remote Docker host. It is easily installed and communicates with the Portainer host via a secure API connection. Once the Portainer agent is installed, you can onboard the remote host in the Portainer dashboard using the simple wizardized process shown above.

Wrapping Up

I have written about Portainer quite a bit. It is a great solution for managing remote Docker hosts using the agent. It makes configuring and managing remote container hosts a breeze. For home lab and production environments, I highly recommend it for managing Docker, Docker Swarm, Kubernetes, etc. While the Docker command line is great for having access to all the features that Docker offers, having the GUI management of Portainer and the ability to easily remotely manage your container environment is a game changer for container management at scale.

Subscribe to VirtualizationHowto via Email ๐Ÿ””

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Brandon Lee

Brandon Lee is the Senior Writer, Engineer and owner at and has over two decades of experience in Information Technology. Having worked for numerous Fortune 500 companies as well as in various industries, Brandon has extensive experience in various IT segments and is a strong advocate for open source technologies. Brandon holds many industry certifications, loves the outdoors and spending time with family.

Related Articles

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.