[Feature Request] Allow Portainer Agent to Ignore Swarm Mode When Used Only for Overlay Networking

Open
#750 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
54/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
docker, go
Domain
backend, devops

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 run or docker compose up -d.
  • We do not deploy applications with docker service create or docker 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:

  1. Portainer treats this Agent-connected host as a standalone Docker environment for management and UI purposes.
  2. Local containers, Compose applications, images, volumes, and networks remain manageable as usual.
  3. Swarm-specific cluster management is disabled or hidden for that environment.
  4. Docker Swarm and the existing overlay network remain active on the host; the option must not run docker swarm leave or change Docker's actual network configuration.
  5. 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from portainer/agent

All issues in portainer/agent

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.