Ambientes e agentes do Portainer
Um ambiente é um servidor ou cluster cadastrado no Portainer para gerenciamento. A conexão por socket ou agente permite que você consulte os recursos desse ambiente no mesmo painel usado para os outros servidores.
Ficha e sumário da página
- Referência técnica
- Portainer 2.45.3
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
Um Server para vários servidores
O Portainer Server guarda o cadastro de todos os ambientes no próprio banco, no volume montado em /data. A tela de ambientes lista cada um com o nome, o endereço que o Server usa para se conectar, o IP público opcional onde as portas publicadas ficam acessíveis, o grupo e as tags. A tela inicial do painel mostra esses ambientes lado a lado. O menu de recursos troca de servidor quando você escolhe outro ambiente.
A documentação da versão 2.45 recomenda um único Server por conjunto de ambientes. Rodar duas instâncias do Server para administrar os mesmos clusters não tem suporte oficial. O Server fica num servidor de gerência, com os agentes nos demais. Os agentes não guardam estado próprio, porque tudo o que eles leem volta ao Server. Por isso a cópia de segurança do Portainer é a cópia do volume /data do Server.
O ambiente local, pelo socket
Na instalação, o Server recebe o socket /var/run/docker.sock montado no container. O assistente da configuração inicial detecta esse socket e cadastra o Docker do próprio servidor como o primeiro ambiente. Numa VPS única, esse é o único ambiente necessário. O Server fala com o Docker local pelo arquivo do socket, sem porta aberta na rede.
O cadastro manual de um Docker Standalone também aceita a conexão direta à API do Docker por TCP. Essa forma exige que o Docker do servidor remoto escute numa porta de rede protegida por TLS. Qualquer máquina que alcance essa porta com um certificado válido controla o Docker inteiro. Os agentes existem para evitar essa exposição.
O Portainer Agent, na porta 9001
O Portainer Agent é um container que roda no servidor remoto, com acesso ao socket do Docker daquela máquina. O Server abre a conexão até o agente na porta 9001, em HTTPS, com certificados gerados pelo próprio agente na instalação. O cadastro do ambiente recebe o endereço e a porta do agente sem protocolo, porque a conexão usa o HTTPS do próprio agente.
A documentação classifica o Agent clássico como opção de legado, mantida para redes locais. A conexão parte do Server, então o servidor remoto precisa deixar a porta 9001 acessível para o Server. Recursos mais novos, como as políticas de governança de frota, não funcionam com o Agent clássico.
Num Docker Swarm, o agente roda em modo global, uma réplica por nó do cluster. Assim o Server enxerga os containers e os volumes de todos os nós pela mesma conexão. A stack de Swarm publicada pela Portainer, o arquivo portainer-agent-stack.yml, segue esse desenho, com o Server falando com o endereço tasks.agent:9001.
O Edge Agent, pelo túnel
O Edge Agent inverte a direção da conexão. Em vez de o Server procurar o agente, o agente consulta o Server em intervalos regulares para saber se existe alguma tarefa pendente. O intervalo padrão é de 5 segundos e muda nas configurações do ambiente. O servidor remoto não abre porta nenhuma para a internet, porque toda conexão sai dele em direção ao Server:
Cadastro
Edge Agent StandardO Server gera o comando de instalação com o token do ambiente.
Consulta
https://portainer:9443O agente pergunta ao Server, a cada 5 segundos, se há tarefa.
Túnel
portainer:8000Com tarefa pendente, o agente abre o túnel TLS até a porta 8000.
Ação
/var/run/docker.sockO agente executa a ação no Docker do servidor remoto.
Por isso o Server precisa expor a interface e o túnel aos servidores remotos. A interface usa normalmente a porta 9443, enquanto o túnel usa a 8000. O exemplo oficial com Traefik publica cada serviço num domínio pela porta 443, como mostra a página O Portainer atrás do Traefik. O endereço de túnel personalizado tem campo próprio apenas na Business Edition. Na Community Edition, a documentação remete ao ajuste descrito na issue 6251 do projeto. Quando o Server usa um certificado autoassinado, EDGE_INSECURE_POLL=1 permite a consulta sem verificar a confiança desse certificado.
A documentação recomenda o Edge Agent na maior parte dos cenários. Ele atende servidores fora da rede do Server, como uma VPS em outro provedor, porque só o Server precisa estar acessível. No modo Async, exclusivo da Business Edition, não existe túnel. O agente envia capturas periódicas do estado do ambiente, com pouco tráfego, para conexões instáveis ou redes móveis com franquia.
No cadastro, você lista as variáveis do host que o Edge Agent recebe. Por segurança, esse repasse aceita apenas variáveis com o prefixo PORTAINER_. Isso não limita as variáveis usadas para configurar o próprio agente, como AGENT_SECRET. As opções estão na referência oficial de configuração.
Grupos, tags e acesso
Os ambientes se organizam em grupos e recebem tags. Um grupo define o acesso de vários ambientes de uma vez. Um usuário ou um team liberado no grupo herda o acesso a todos os ambientes dele, com a marca de herdado na tela de acesso. Um acesso definido direto no ambiente prevalece sobre o do grupo naquele ambiente, com a marca de substituição.
Ao remover um ambiente, as stacks criadas nele perdem o vínculo e ficam órfãs na lista de stacks. Elas continuam visíveis pela opção de mostrar stacks órfãs, à espera de uma nova associação. A remoção não apaga os containers no servidor, porque o Portainer só deixa de administrar aquele Docker.
Limites dos agentes
Os webhooks de stack da Business Edition funcionam só em ambientes com Server ou Agent clássico. Num ambiente Edge, o túnel abre sob demanda, sem endereço permanente para receber a chamada. Os servidores administrados também entram no cálculo de nós da Business Edition. Um servidor exclusivo de gerência fica fora desse cálculo quando não é administrado pelo Portainer, como explica a página Community e Business Edition.
O ambiente define onde a stack roda. O próxima página, Stacks pelo painel, mostra como o Portainer guarda o arquivo Compose de cada app e as variáveis dele.