[Feature Request] Allow Portainer Agent to Ignore Swarm Mode When Used Only for Overlay Networking
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 54/100
Research direction
Start by reading the Agent's automatic cluster mode selection and how the server represents Agent-connected environments; the issue does not name specific files or tests. Trace where Docker Swarm state influences that behavior, then identify how an opt-out could preserve the daemon's active Swarm and overlay networking. Done means the opt-out manages the host as standalone while the default Swarm experience remains unchanged.
Written by the indexing model from the issue text.
Description
Feature request
Please add an opt-out setting that allows Portainer Agent to manage a Docker host as a standalone Docker environment, even when Docker Swarm is active solely to provide cross-host overlay networking.
For example, an environment variable such as:
AGENT_IGNORE_SWARM=true
The name is only a suggestion; an equivalent option in Portainer's environment settings would also work.
Use case
We have two Docker hosts joined to the same Swarm cluster using docker swarm init and docker swarm join. Swarm is enabled only for overlay networking so that containers on different hosts can communicate.
We do not use Swarm for application orchestration:
- Containers are started with
docker runordocker compose up -d. - We do not deploy applications with
docker service createordocker stack deploy. - We want to manage the hosts and their locally deployed containers independently in Portainer.
- An attachable overlay network provides the cross-host connectivity we need.
Although the operational model is standalone Docker plus shared networking, the Docker Engine correctly reports Swarm: active. Portainer Agent detects this and switches to Swarm/cluster behavior, which is not desirable for this deployment model. Swarm-related navigation and management features become unnecessary and may produce confusing behavior or errors.
Expected behavior
When the proposed setting is enabled:
- Portainer treats this Agent-connected host as a standalone Docker environment for management and UI purposes.
- Local containers, Compose applications, images, volumes, and networks remain manageable as usual.
- Swarm-specific cluster management is disabled or hidden for that environment.
- Docker Swarm and the existing overlay network remain active on the host; the option must not run
docker swarm leaveor change Docker's actual network configuration. - The default behavior stays unchanged when the setting is absent or
false.
The setting should be an explicit opt-out: users who deploy Swarm services and stacks should continue to get Portainer's normal Swarm experience.
Current workaround
Because the Agent does not currently provide this option, we run a small Docker API proxy between the Agent and the Docker daemon:
Portainer Agent
|
v
Local Unix socket bridge
|
v
Docker API shim
|
v
Real Docker socket / Docker Engine
The shim forwards the Docker API but modifies the /info response so the Agent sees Swarm as inactive, including fields such as:
{
"Swarm": {
"LocalNodeState": "inactive",
"ControlAvailable": false,
"NodeID": "",
"NodeAddr": "",
"Cluster": null
}
}
This is a fragile workaround. It adds another component with privileged access to the Docker API, depends on the /info response format, and may break when Docker or Portainer changes.
Suggested implementation
Support an opt-out flag, for example:
services:
agent:
image: portainer/agent:2.45.1
environment:
AGENT_IGNORE_SWARM: "true"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /var/lib/docker/volumes:/var/lib/docker/volumes
- /:/host
restart: always
This is an illustration of the requested API only; AGENT_IGNORE_SWARM is not an existing supported option.
Ideally, the setting would bypass automatic cluster-mode selection without changing the Docker daemon's actual state. If Portainer Server also needs to recognize this choice to provide a standalone UI, please consider exposing the same behavior through the environment configuration.
Related issue
This request is related to #341, which discusses avoiding automatic Agent cluster mode. The specific requirement here is to keep Swarm enabled for overlay networking while managing each host as standalone Docker.
Thank you for considering this feature.
- Dominant language
- Go
- Stars
- 596
- Forks
- 98
- PR merge metrics
- No merged PRs in 30d
Getting set up
This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from portainer/agent
-
Difficulty 3/5 1-2 days Newbie friendliness 70/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 55/100
-
Difficulty 4/5 3-5 days Newbie friendliness 38/100
-
Difficulty 5/5 Over a week Newbie friendliness 20/100
-
Difficulty 5/5 Over a week Newbie friendliness 25/100
Similar issues
-
☢️ Bug v3
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
area/import-export area/projects concern/ux
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
go-vikunja/vikunja#4455 · 1 comment ·
Maintainers usually reply within 2 days
-
Dependabot PRs no longer merge automaticallyPossibly taken @dwisiswant0 claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
projectdiscovery/urlfinder#160 ·
Maintainers usually reply within 1 day
-
database
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
chnm/legal-modernism#450 ·
Maintainers usually reply within 1 day
-
tech-debt
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 1 day