Portainer Agent
Agent for remote Docker management.
[i]Overview
Portainer Agent is a lightweight proxy service that enables secure remote Docker management without directly exposing the Docker daemon's API. Originally developed as part of Portainer's ecosystem, the agent creates a secure bridge between a Portainer server instance and remote Docker hosts, allowing centralized container management across multiple nodes. Unlike exposing the Docker socket over TCP (which poses significant security risks), Portainer Agent provides a controlled interface that filters and validates commands before executing them on the host system.
This deployment creates a standalone agent service that connects to your Docker daemon through the local socket while exposing a secure API endpoint on port 9001. The agent mounts both the Docker socket for container operations and the volumes directory for complete volume management capabilities. This architecture allows a remote Portainer server to perform full Docker operations including container lifecycle management, image operations, network configuration, and volume administration without requiring direct Docker API access.
Homelab enthusiasts and system administrators managing multiple Docker hosts will find Portainer Agent invaluable for centralizing container operations. Rather than SSH-ing into individual hosts or maintaining separate Portainer instances, the agent enables single-pane-of-glass management of distributed Docker environments. This approach is particularly valuable for hybrid setups where some hosts run behind firewalls or NAT, as the agent can establish outbound connections to Portainer servers while maintaining security boundaries.
[*]Key Features
- [+]Secure Docker API proxy without exposing raw Docker socket over network
- [+]Complete volume management through direct /var/lib/docker/volumes access
- [+]Filtered command execution with built-in security validation
- [+]Lightweight footprint requiring only 64MB RAM minimum
- [+]Support for both agent-initiated and server-initiated connections
- [+]Compatible with Portainer Business Edge Agent functionality
- [+]Real-time container logs and statistics streaming
- [+]Network topology discovery and management capabilities
[#]Common Use Cases
- [1]Managing Docker hosts behind firewalls or NAT from central Portainer server
- [2]Homelab setups with multiple Raspberry Pi or mini-PC Docker nodes
- [3]Remote server management without SSH access or VPN requirements
- [4]MSP environments managing client Docker infrastructure remotely
- [5]Development teams needing shared access to staging Docker environments
- [6]Edge computing deployments with intermittent connectivity to central management
- [7]Multi-site Docker management across geographically distributed locations
[!]Prerequisites
- [!]Docker Engine installed on target host with daemon running
- [!]Minimum 64MB available RAM (128MB recommended for busy hosts)
- [!]Port 9001 available and accessible from Portainer server network
- [!]Docker socket access permissions for the agent container
- [!]Existing Portainer server instance (Community or Business Edition)
- [!]Network connectivity between Portainer server and agent on port 9001
[!]
WARNING: For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms
[$]docker-compose.yml
[docker-compose.yml]
1services: 2 portainer-agent: 3 image: portainer/agent:latest4 container_name: portainer-agent5 restart: unless-stopped6 volumes: 7 - /var/run/docker.sock:/var/run/docker.sock8 - /var/lib/docker/volumes:/var/lib/docker/volumes9 ports: 10 - "9001:9001"[$].env Template
[.env]
1# No additional config needed[i]Usage Notes
- [1]Docs: https://docs.portainer.io/admin/environments/add/docker/agent
- [2]Agent listens on port 9001
- [3]Add in Portainer: Environments > Add environment > Agent
- [4]Enter agent IP:9001 to connect
- [5]Enables remote container management without direct Docker socket access
- [6]More secure than exposing Docker API directly
[>]Quick Start
[terminal]
1# 1. Create the compose file2cat > docker-compose.yml << 'EOF'3services:4 portainer-agent:5 image: portainer/agent:latest6 container_name: portainer-agent7 restart: unless-stopped8 volumes:9 - /var/run/docker.sock:/var/run/docker.sock10 - /var/lib/docker/volumes:/var/lib/docker/volumes11 ports:12 - "9001:9001"13EOF1415# 2. Create the .env file16cat > .env << 'EOF'17# No additional config needed18EOF1920# 3. Start the services21docker compose up -d2223# 4. View logs24docker compose logs -f[>]One-Liner
Run this command to download and set up the recipe in one step:
[terminal]
1curl -fsSL https://docker.recipes/api/recipes/portainer-agent/run | bash[?]Troubleshooting
- [!]Connection refused on port 9001: Verify agent container is running and port binding is correct with 'docker ps'
- [!]Agent appears offline in Portainer: Check network connectivity and firewall rules between Portainer server and agent host
- [!]Permission denied accessing Docker socket: Ensure Docker daemon is running and socket permissions allow container access
- [!]Volume operations failing: Verify /var/lib/docker/volumes mount exists and has proper permissions
- [!]Agent disconnects frequently: Check for Docker daemon restarts or network instability between hosts
- [!]Cannot add environment in Portainer: Ensure agent URL format is correct (http://agent-ip:9001) and agent is responding
Community Notes
Loading...
Loading notes...
## Download Recipe Kit
Get all files in a ready-to-deploy package
Includes docker-compose.yml, .env template, README, and license
## Components
portainer-agent
## Tags
#portainer#docker#management#agent
## Category
Home Lab & Self-HostingShortcuts: C CopyF FavoriteD Download