If you’re already using Portainer to manage your containers, you know how much it simplifies deployments and monitoring. But what if you’re running containers on multiple servers? Logging into each machine separately to check logs, restart containers, or deploy updates can quickly become a hassle.
This is where Portainer Agent comes in. Designed to work alongside Portainer Server, the agent allows you to manage remote Docker instances from a single dashboard—no need for SSH access or manual configurations. With Portainer Agent, you can:
- Deploy and update containers across multiple machines effortlessly
- Monitor container logs and statuses in real time
- Manage container networks, volumes, and images without direct server access
In this article, we will go through the process of setting up Portainer Agent on remote servers and integrate it with your existing Portainer Server, making multi-server container management faster and more efficient.
What We'll Need to Get Started
An Instance of Portainer Server
We will need to have a Portainer Server deployed on one of our servers. This is where we will be managing deployments across our home network. If you haven't installed Portainer Server, check out the following article for further details:
Antonio Vargas
Docker Installed in Each Server to be Managed
Since we are going to use Docker to install Portainer Agent, we will need to have Docker installed in each of the servers that will be managed remotely. You can check the article Docker Setup and Storage Management for more details, or use the following steps to get this done quickly (for Linux only):
# Install Docker using their magic script
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh ./get-docker.sh --dry-run
# Add our user to the Docker group
sudo usermod -aG docker $USER
newgrp docker
# Enable the Docker service to auto-start after boot
sudo systemctl enable --now docker
# Create the folder to store our application data
sudo mkdir -p /srv/appdata/
sudo chown $USER /srv/appdata/A Note On Security
When running Portainer Agent on a remote node, it listens for connections from the Portainer Server. By default, these connections are unprotected. While we mitigate risk by ensuring the Portainer Agent’s listening port is not exposed to the open internet, a more secure approach is to require authentication between the Portainer Server and its agents.
To enable authentication, you should generate a strong secret key that the Portainer Server will use to authenticate with the agents. You can use an online tool to generate a secure key, for example, the Password Generator from 1Password. I recommend using the default parameters (20 characters long, without special characters) is recommended.
Next, you need to configure the Portainer Server to use this secret. This requires updating the Portainer Server’s startup parameters. Since container settings cannot be modified dynamically, you must stop and remove the existing Portainer Server container. If you followed the steps in the Simple Container Management With Portainer guide, your application data will persist, as it is stored outside the container.
PORTAINER_WEB=9000 # Change to choose a different localhost port
APP_DATA=/srv/appdata # Change to use a different application data root
SECRET_VALUE=<secret> # Replace with your secure secret
# Remove the existing container (if previosly created)
docker stop portainer
docker rm portainer
# Create the container with the updated configuration
docker run -d \
-p ${PORTAINER_WEB}:9000 \
--name portainer \
--restart=always \
-v /var/run/docker.sock:/var/run/docker.sock \
-v ${APP_DATA}/portainer:/data \
-e AGENT_SECRET=${SECRET_VALUE}
portainer/portainer-ce:latestCreating a Remote Environment in Portainer
In Portainer, remote nodes appear as separate Environments within the Portainer Server. To add a new node, you need to create a new Environment. Follow these steps for each remote node you want to manage:
- Open the Portainer Web UI, navigate to the Environments dashboard, and click on Add environment (top-right).
- In the Environment Wizard, select Docker Standalone as the environment type.
- In the next step, choose Agent as the connection method.
- Enter a descriptive Name for the environment (using the remote server’s hostname or IP address is recommended).
- Set the Environment address of the agent as:
<IP_OF_REMOTE_SERVER>:9001 - Copy the command that appears in the text box by clicking Copy command.
- Connect to the remote server (e.g., via SSH) and run the copied command.
- Once the command completes, return to the Portainer Web UI and click Connect.
- Go back to the Home dashboard.
Adding a New Environment in Portainer
Verifying the New Environment
You should now see the newly added server listed under Environments in the Home dashboard. If Portainer Server is also managing containers locally, you will see a Local environment in this list as well.
Managing Remote Environments
Once an environment appears on your Home dashboard, you can click on its card to access its dashboard. From the left-side menu, you can:
- Deploy templates
- Create and manage stacks, containers, networks, and volumes
Removing an Environment
If you need to remove an environment:
- Navigate to Environments under Administration (left-side menu).
- Select the checkbox next to the environment(s) you want to remove.
- Click Remove at the top.
If you ever need to re-add a removed environment, simply follow the steps from the previous section.
What's Next?
Now that you’ve set up one or more Environments in Portainer, you can start deploying and managing services from a centralized Web UI. Here are a few things to explore next:
- Check out the article Scalable Server Monitoring With Prometheus for information on how to deploy a remote monitoring stack for all your home-lab servers.
- Look at other templates available at our GitHub repository for additional self-hosting ideas.
