Portainer Edge Agent Setup Guide

Overview

Edge Agent allows you to connect Docker environments to Portainer over the network instead of using local socket connection. This is useful when having socket connection issues.

Reference: https://downloads.portainer.io/edge_agent_guide.pdf

Step 1: Access Portainer UI

Access your Portainer instance:

HTTP: http://localhost:9000
HTTPS: https://localhost:9443

Complete the initial setup if you haven't already (create admin user).

Step 2: Add Edge Environment in Portainer UI

Log into Portainer
Go to Environments (left sidebar)
Click "Add environment"
Select "Edge Agent Standard"
- Choose "Docker Standalone"
- Name: nuc-edge (or your preferred name)

Copy the deployment command shown in the UI

It will include your EDGE_ID and EDGE_KEY
The command looks like:

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  -v /:/host \
  -v portainer_agent_data:/data \
  --restart always \
  -e EDGE=1 \
  -e EDGE_ID=xxx \
  -e EDGE_KEY=xxx \
  -e CAP_HOST_MANAGEMENT=1 \
  -e EDGE_INSECURE_POLL=1 \
  --name portainer_edge_agent \
  portainer/agent:latest

Extract EDGE_ID and EDGE_KEY from the command

Step 3: Configure Edge Agent

Option A: Using docker-compose (Recommended)

Copy the example env file:

cd /mnt/shared/DEV/repos/d-popov.com/scripts/portainer-compose-stacks
cp .env.edge-agent.example .env

Edit .env file with your EDGE_ID and EDGE_KEY:
```
nano .env
```

Start the Edge Agent:

docker-compose -f portainer-edge-agent.yml up -d

Option B: Using the Docker command directly

Just run the command copied from Portainer UI in Step 2.

Step 4: Verify Connection

Go back to Portainer UI → Environments
Your edge environment should show as "Connected" (green)
Click on the environment to manage your Docker containers

Troubleshooting

Edge Agent not connecting:

Check logs:
```
docker logs portainer-edge-agent
```
Verify Portainer tunnel is accessible:
```
curl http://localhost:8000
```
Check if agent container is running:
```
docker ps | grep edge-agent
```
Ensure firewall allows port 8000 (for Edge polling)

Environment shows as "Down":

Wait 30-60 seconds for initial connection
Check that EDGE_ID and EDGE_KEY are correct
Restart the agent: docker restart portainer-edge-agent

Cleanup

To remove Edge Agent:

docker-compose -f portainer-edge-agent.yml down -v
# or
docker stop portainer-edge-agent && docker rm portainer-edge-agent

Notes

Edge Agent polls Portainer server every 5 seconds by default
EDGE_INSECURE_POLL=1 allows connection without TLS (for local testing)
Port 8000 is used for the Edge tunnel communication
Port 9001 is the agent API port (optional, for direct access)

3.0 KiB Raw Blame History