Website • Documentation • GitHub
The Portainer Agent enables secure communication between a Portainer server and remote Docker environments. Deploy it on remote hosts to manage them from a central Portainer instance.
- Remote Management — Manage Docker hosts from a central location
- Secure Communication — Encrypted WebSocket connections
- Multi-Environment — Works with Docker standalone, Swarm, and Kubernetes
- Lightweight — Minimal resource footprint
- Auto-Discovery — Automatically detects containers, networks, and volumes
- Firewall-Friendly — Single port communication
- Docker and Docker Compose
- External Docker network
- Portainer CE or BE server (see portainer-ce)
Edit docker-compose.yml:
- Replace
your-networkwith your Docker network name
docker compose up -d- In your Portainer server, go to Environments → Add environment
- Select Agent
- Enter the agent URL:
your-remote-host:9001 - Give it a name and connect
The agent works with default settings, but you can customize:
| Variable | Description | Default |
|---|---|---|
AGENT_CLUSTER_ADDR |
Address for cluster communication | - |
AGENT_SECRET |
Shared secret for authentication | - |
LOG_LEVEL |
Logging verbosity | INFO |
| Port | Service | Description |
|---|---|---|
| 9001 | TCP | Agent API |
| Path | Description |
|---|---|
/var/run/docker.sock |
Docker socket (required) |
/var/lib/docker/volumes |
Docker volumes (for browsing) |
Only allow port 9001 from your Portainer server:
# UFW example
ufw allow from YOUR_PORTAINER_IP to any port 9001For additional security, set a shared secret:
environment:
- AGENT_SECRET=your-secure-secretThen configure the same secret in Portainer when adding the environment.
Deploy the agent on each remote host you want to manage. Each agent gets its own entry in Portainer.
- Check firewall allows port 9001
- Verify Docker socket is mounted correctly
- Check agent logs:
docker logs portainer-agent
Ensure the Docker socket is accessible:
ls -la /var/run/docker.sockPortainer Agent is released under the zlib License.