Skip to main content

Edge Agent Overview

What is Portainer Edge Agent?​

The Portainer Edge Agent is a lightweight container that enables remote management of Docker environments through Portainer Server. It's specifically designed for environments that are:

  • Behind firewalls
  • In private networks
  • Accessible only via VPN
  • Not reachable by direct inbound connections

How Edge Agent Works​

Connection Model​

Customer Environment          Vendor/Managed Environment
┌──────────────────┐         ┌───────────────────┐
│  Edge Agent      │────────>│ Portainer Server  │
│  (Outbound only) │  HTTPS  │                   │
└──────────────────┘         └───────────────────┘

Key Point: The Edge Agent initiates the connection. Portainer Server does not connect to the customer environment.

Communication Flow​

  1. Agent Starts: Edge Agent container starts and reads its configuration
  2. Outbound Connection: Agent connects to Portainer Server URL via HTTPS
  3. Authentication: Agent authenticates using its unique token
  4. Tunnel Established: Secure WebSocket tunnel is created
  5. Command Reception: Agent receives stack deployment/management commands
  6. Local Execution: Agent executes Docker commands on local Docker engine
  7. Status Reporting: Agent sends container status and metrics back to server

Network Access Requirements​

Required Outbound Access​

The Edge Agent requires outbound HTTPS access to:

  • Destination: Portainer Server URL (e.g., portainer.vendor.com)
  • Port: 443 (HTTPS)
  • Protocol: HTTPS/WebSocket
  • Frequency: Continuous connection (with automatic reconnection)

Firewall Rules​

Required Rule:

Source: Edge Agent container
Destination: Portainer Server FQDN/IP
Port: 443
Protocol: TCP (HTTPS)
Direction: Outbound

No Inbound Rules Required: Edge Agent does not listen on any ports accessible from outside the Docker host.

Edge Agent Deployment​

Installation Steps​

  1. Obtain Edge Agent Command from Portainer Server
  2. Run Edge Agent Container on Docker host
  3. Verify Connection in Portainer Server UI
  4. Deploy Chatty AI Stack through Portainer

Example Edge Agent Deployment​

docker run -d \
  --name portainer_edge_agent \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  -v /:/host \
  -e EDGE_ID=<edge-id> \
  -e EDGE_KEY=<edge-key> \
  -e EDGE_INSECURE_POLL=0 \
  portainer/agent:latest

Note: Actual command is provided by Portainer Server with pre-configured tokens.

Security Considerations​

Edge Agent Token​

  • Treat as Secret: Edge Agent token provides full access to Docker environment
  • Rotate Regularly: Update tokens periodically for security
  • Limit Exposure: Do not commit tokens to version control
  • Monitor Usage: Track which environments are connected

Docker Socket Access​

Edge Agent requires access to Docker socket (/var/run/docker.sock) to manage containers. This provides:

  • Full container management capabilities
  • Volume management
  • Network management
  • Image management

Security Implication: Edge Agent has full Docker access. Ensure Portainer Server is secured.

Network Security​

  • TLS Encryption: All communication is encrypted via HTTPS/TLS
  • Certificate Validation: Edge Agent validates Portainer Server certificate
  • Firewall Protection: Only outbound connection required
  • VPN Compatible: Works through VPN tunnels

Edge Agent Features​

Stack Management​

  • Deploy Docker Compose stacks
  • Update running stacks
  • Remove stacks
  • View stack status

Container Management​

  • Start/stop/restart containers
  • View container logs
  • Execute commands in containers
  • Inspect container details

Volume Management​

  • List volumes
  • Inspect volume details
  • Browse volume contents (with limitations)

Image Management​

  • Pull images from registries
  • List local images
  • Remove unused images
  • View image details

Monitoring and Health​

Connection Status​

Portainer Server shows Edge Agent connection status:

  • Connected: Agent is online and responsive
  • Disconnected: Agent is offline or unreachable
  • Heartbeat: Last communication timestamp

Automatic Reconnection​

If connection is lost, Edge Agent automatically:

  1. Detects disconnection
  2. Waits for reconnection interval
  3. Attempts to reconnect
  4. Continues retry until successful

Health Checks​

Monitor Edge Agent health by:

  • Checking container status: docker ps | grep portainer_edge_agent
  • Viewing container logs: docker logs portainer_edge_agent
  • Verifying connection in Portainer Server UI

Troubleshooting Edge Agent​

Agent Not Connecting​

Symptoms: Edge Agent container running but not showing as connected in Portainer Server.

Checks:

  1. Verify outbound HTTPS access to Portainer Server
  2. Check Edge Agent logs for connection errors
  3. Verify Edge ID and Edge Key are correct
  4. Confirm Portainer Server URL is accessible
  5. Check firewall rules allow outbound 443

Agent Disconnecting Frequently​

Symptoms: Edge Agent connects but drops connection repeatedly.

Checks:

  1. Network stability between agent and server
  2. Firewall not blocking persistent connections
  3. Proxy or load balancer timeout settings
  4. Edge Agent container resource limits

Cannot Deploy Stack​

Symptoms: Edge Agent connected but stack deployment fails.

Checks:

  1. Docker socket is properly mounted
  2. Sufficient disk space for images and volumes
  3. Image registry is accessible from Docker host
  4. Environment variables are correctly set
  5. Volume mount paths exist on host

Edge Agent vs Direct Docker Access​

FeatureEdge AgentDirect Docker Access
Remote Management✅ Yes❌ Requires SSH/VPN
Inbound Firewall Rules✅ Not required❌ Required
GUI Management✅ Yes❌ Command-line
Centralized Control✅ Yes❌ Per-host
Audit Trail✅ Built-in⚠️ Manual
Learning Curve⚠️ Moderate✅ Standard Docker
Dependency⚠️ Portainer Server✅ None

Best Practices​

  1. Secure Portainer Server: Use strong authentication and RBAC
  2. Monitor Connection: Set up alerts for Edge Agent disconnections
  3. Regular Updates: Keep Edge Agent image updated
  4. Token Rotation: Rotate Edge Agent tokens periodically
  5. Network Monitoring: Monitor outbound connections to Portainer Server
  6. Backup Configuration: Document Edge Agent deployment parameters
  7. Test Connectivity: Verify network path before deployment
  8. Resource Limits: Set appropriate resource limits for Edge Agent container

Portainer Edge Agent Implications for VPN Deployments​

When Chatty AI is deployed in a VPN-protected environment:

Advantages​

  • No VPN Inbound Rules: Edge Agent only needs outbound access
  • Simplified Firewall: No need to expose management ports through VPN
  • Vendor Access: Vendor can manage deployment without VPN access to customer network
  • Security: Customer network remains protected; only outbound tunnel exists

Requirements​

  • Outbound VPN Route: Ensure VPN allows outbound HTTPS to Portainer Server
  • DNS Resolution: Portainer Server FQDN must be resolvable
  • Persistent Connection: VPN must support long-lived connections
  • Reconnection: VPN should allow automatic reconnection after drops

Considerations​

  • If Portainer Server is vendor-managed, customer must allow outbound access
  • If Portainer Server is customer-managed, it should be accessible from VPN
  • Network teams must whitelist Portainer Server destination
  • Monitor VPN connection stability for Edge Agent reliability

Cross-Reference​