docker.recipes

Portainer Agent

beginner

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:latest
4 container_name: portainer-agent
5 restart: unless-stopped
6 volumes:
7 - /var/run/docker.sock:/var/run/docker.sock
8 - /var/lib/docker/volumes:/var/lib/docker/volumes
9 ports:
10 - "9001:9001"

.env Template

.env
1# No additional config needed

Usage Notes

  1. 1Docs: https://docs.portainer.io/admin/environments/add/docker/agent
  2. 2Agent listens on port 9001
  3. 3Add in Portainer: Environments > Add environment > Agent
  4. 4Enter agent IP:9001 to connect
  5. 5Enables remote container management without direct Docker socket access
  6. 6More secure than exposing Docker API directly

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4 portainer-agent:
5 image: portainer/agent:latest
6 container_name: portainer-agent
7 restart: unless-stopped
8 volumes:
9 - /var/run/docker.sock:/var/run/docker.sock
10 - /var/lib/docker/volumes:/var/lib/docker/volumes
11 ports:
12 - "9001:9001"
13EOF
14
15# 2. Create the .env file
16cat > .env << 'EOF'
17# No additional config needed
18EOF
19
20# 3. Start the services
21docker compose up -d
22
23# 4. View logs
24docker 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

Ad Space