[Feature] Allow disabling internal agent

[raclo]

What’s the bug?

Agent communication timeout

Description

Environment

• Tugtainer version: latest (quenary/tugtainer:latest)
• Platform: Docker standalone (no swarm)
• OS: QNAP NAS (QTS 5.x, Docker 24.x)
• Network: Custom user-defined bridge, containers reachable via name resolution
• Docker setup: All services deployed via Portainer stack

---

Expected behavior

Tugtainer should communicate with its tugtainer-agent container and list containers/images successfully.

---

Actual behavior

UI partially loads:

• Containers list works intermittently.
• Images list fails (500 Internal Server Error).
• Container checks return TimeoutError.

Logs show repeated internal timeouts and failed self-detection:

aiohttp.client_exceptions.ClientResponseError: 424, message='Failed Dependency', url='http://127.0.0.1:8001/api/container/exists/
'
...
aiohttp.helpers.TimeoutError

Even when tugtainer and tugtainer-agent are in the same network and reachable (verified with curl):

Connected to tugtainer-agent (172.29.12.3) port 8001
< HTTP/1.1 405 Method Not Allowed

This confirms network reachability, but backend still attempts to connect to 127.0.0.1:8001.

---

Troubleshooting done

• Verified agent reachable inside the container (curl → 405 OK).
• Rebuilt stack with clean volumes.
• Set env vars:

  AGENT_ADDRESS=http://tugtainer-agent:8001
  AGENT_SECRET=PuzzolaTug!1
  SELF_CONTAINER_ENABLED=false
  AGENT_ENABLED=false
  
  

Verified via docker inspect → correct IPs and shared network.

Behavior persists; backend still calls 127.0.0.1:8001.

Additional notes

Setting DOCKER_HOST=tcp://docker-socket-proxy:2375 causes 403 Forbidden (expected, since it’s not the right target).

Suggest reviewing default agent discovery: the backend keeps initializing its internal agent even when AGENT_ENABLED=false.

Logs show no request reaching tugtainer-agent.

Suggested fix

Respect AGENT_ADDRESS and disable self-agent logic when external agent is configured.

Expose a clear /healthz endpoint on backend for easier debugging.

Optionally provide environment variable FORCE_AGENT_ONLY=true to bypass localhost binding.

This behavior was reproducible across multiple clean deployments and confirmed that network and agent containers are healthy — issue appears to be in the backend connection handling.

Expected behaviour

Tugtainer should communicate with the external tugtainer-agent container (configured via AGENT_ADDRESS) and successfully list containers and images.

To reproduce

1. Deploy Tugtainer + Tugtainer-Agent using Docker Compose on a standalone Docker host (no Swarm).
2. Place both containers in the same network (e.g. mianet).
3. Set the following environment variables for Tugtainer:

AGENT_ADDRESS=http://tugtainer-agent:8001
AGENT_SECRET=PuzzolaTug!1
AGENT_ENABLED=false
SELF_CONTAINER_ENABLED=false
DOCKER_HOST=tcp://docker-socket-proxy:2375

4. Open Tugtainer UI and refresh container and image lists.

5. Observe that:

   • containers endpoint works intermittently,
     

   • images and check actions fail with 500 Internal Server Error,
     

   • logs show backend still calling 127.0.0.1:8001.
     

Platform

OS: QNAP NAS (QTS 5.x, Docker 24.x)

Versions

Docker version 27.1.2-qnap7, build d46fd47
quenary/tugtainer:latest (as of Nov 2025)
quenary/tugtainer-agent:latest (as of Nov 2025)

Relevant log output

aiohttp.client_exceptions.ClientResponseError: 424, message='Failed Dependency', url='http://127.0.0.1:8001/api/container/exists/<id>'
aiohttp.helpers.TimeoutError
BACKEND - ERROR - Failed to get self container object from client 1
Agent logs are empty — no requests received from backend even though reachable via network:

curl http://tugtainer-agent:8001/api/container/list → HTTP 405 (expected, endpoint exists)

Extra

Verified agent reachability via curl from inside the Tugtainer container.

Removing the agent and running Tugtainer alone yields same timeout errors.

Using DOCKER_HOST=tcp://docker-socket-proxy:2375 results in:

403 Forbidden – url='http://docker-socket-proxy:2375/api/public/health'

Problem seems in backend logic that still initializes self-agent (127.0.0.1) even with external agent configured.

[Quenary]

Hi.
It is not a bug, but expected behaviour because the main image does not support disabling of internal agent.
This issue must be of type feature request.
And please explain why this would be useful.

[raclo]

Thanks for clarifying - converting this to a feature request. The ability to disable the internal agent and connect only to an external one would be useful for: * running Tugtainer in secure environments (NAS / corporate hosts) where /var/run/docker.sock cannot be mounted, * improving stability and isolation, since the backend and agent can restart independently, * enabling multi-host or proxied setups (via docker-socket-proxy). A simple env var like AGENT_MODE=external AGENT_ADDRESS=http://tugtainer-agent:8001 AGENT_SECRET=<secret> would fully solve this and keep backward compatibility. Happy to test a preview build if you release one. Raclo Da: Eugene Savin ***@***.***> Inviato: martedì 4 novembre 2025 17:22 A: Quenary/tugtainer ***@***.***> Cc: raclo ***@***.***>; Author ***@***.***> Oggetto: Re: [Quenary/tugtainer] [Bug] Agent communication timeout and self-container detection failures on Docker standalone setup (Issue #45) [https://avatars.githubusercontent.com/u/39758069?s=20&v=4]Quenary left a comment (Quenary/tugtainer#45)<#45 (comment)> Hi. It is not a bug, but expected behaviour because the main image does not support disabling of internal agent. This issue must be of type feature request. And please explain why this would be useful. - Reply to this email directly, view it on GitHub<#45 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AGKXKNHCW2D2AMKGNISJJ2L33DHDTAVCNFSM6AAAAACLDTIAPCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTIOBWHA2TSOBWG4>. You are receiving this because you authored the thread.Message ID: ***@***.******@***.***>>