Portainer Agent
Agent for remote Docker management.
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
- 1Managing Docker hosts behind firewalls or NAT from central Portainer server
- 2Homelab setups with multiple Raspberry Pi or mini-PC Docker nodes
- 3Remote server management without SSH access or VPN requirements
- 4MSP environments managing client Docker infrastructure remotely
- 5Development teams needing shared access to staging Docker environments
- 6Edge computing deployments with intermittent connectivity to central management
- 7Multi-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
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 neededUsage Notes
- 1Docs: https://docs.portainer.io/admin/environments/add/docker/agent
- 2Agent listens on port 9001
- 3Add in Portainer: Environments > Add environment > Agent
- 4Enter agent IP:9001 to connect
- 5Enables remote container management without direct Docker socket access
- 6More 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 -fOne-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 | bashTroubleshooting
- 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
Ad Space
Shortcuts: C CopyF FavoriteD Download