A Portainer Agent Primer

App A Portainer Agent Primer

UPDATE 1.1 (20220531)

If you run docker on multiple machines as I do, you'll find Portainer Agent an easy “enhancement” to Portainer which will enable you to use a single Portainer instance to manage your docker instances.

Here's how... Let's say you have docker running on a Raspberry Pi (RPi) and two Synology NAS (NAS1, NAS2)

I'm going to use the RPi to host my Portainer container using an HTTP connection. To set up Portainer, running a simple command is all that is required. In this case, execute the following command from the RPi CLI.

sudo docker run -d -p 9000:9000 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce

[See the official Portainer web site for additional installation details.]

Accessing Portainer is simple. From a browser, enter [Client IP]:[9000]. For example...

Now open an SSH instance on your NAS and execute Portainer Agent's install command string (source: Portainer):

sudo 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

But wait... We have an error!

Error response from daemon: Bind mount failed: '/var/lib/docker/volumes' does not exists.

We could create direct directories `/var/lib/docker` and `/var/lib/docker/volumes`.

But this is a brutish workaround, and may not stand up to DSM updates...

[Kudos to @one-eyed-king for the following "fix" to the default Portainer Agent install]

Instead, let's discover where Docker stores its volumes.

Using SSH, enter...

echo "$(sudo docker info --format '{{.DockerRootDir}}')/volumes"

And we see this...

NOTE: This result is specific to my installation and the 'echo' command should be performed on each Portainer Host.

With that information, we can the Portainer Agent install command:

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

Alternately... Use the following Docker run command (thanks again to @one-eyed-king) which sidesteps the need to determine where Docker stores its volumes, and edit Portainer Agent's install script.

sudo docker run -d \ -p 9001:9001 \ --name portainer_agent \ --restart=always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v $(sudo docker info --format '{{.DockerRootDir}}')/volumes:/var/lib/docker/volumes \ portainer/agent

Before we can run the setup command (now edited) again, we must delete the portainer_agent container.

sudo docker stop portainer_agent
sudo docker rm portainer_agent

Now issue the revised docker run command for Portainer Agent.

With that complete, and error-free, let's open the Portainer instance running on the host machine and select "Environments" (I'm running Portainer v2.13.1) and click the "Add environment" button.

For "Environment type", select "Agent".

Under "Environment details" enter a name for your client machine (ex. NAS1).

For the "Environment URL" enter the NAS1 IP, and port 9001.

For example


And click "Add environment". Done.

Select the "Home" menu, and you should see both a "local" (the RPI machine, in this example) and "NAS1" environment. Select the NAS1 environment to view/manage the remote client docker containers.

Add as many docker clients as necessary, by repeating the agent installation on each device.


  • Like
Reactions: Huggy

Similar resources

NextCloud on Synology NAS using Docker compose (with Portainer) SynoMan
The self-hosted productivity platform that keeps you in control
5.00 star(s) 1 ratings
Portainer - Docker container management made easy Rusty
  • Featured
Learn how to configure Portainer on your NAS and elevate your Docker setup to a new level.
5.00 star(s) 1 ratings
Portainer - using stacks (docker-compose) Rusty
  • Featured
How to deploy docker-compose using Portainer stacks feature
5.00 star(s) 2 ratings
Ultimate Starter - Docker, Portainer, Portainer Agents, and Auto-Updating Everything with Watchtower G
Manage Multiple Docker Environments, Automatically Updating All Images and Containers
0.00 star(s) 0 ratings