Docker Agent

Docker Agent

The Docker agent watches one Docker Engine and reports containers to Trove.

It reports:

• container name
• image
• image digest where available
• state
• Docker health status where available
• published ports
• labels, including Compose labels

Run one Docker agent per Docker host.

Run with Docker

Create a Trove token on the server:

docker compose exec server trove-server agent create docker-nuc01

Then run the agent on the Docker host:

docker run -d --name trove-agent-docker --restart unless-stopped \
  -e TROVE_SERVER_URL=http://YOUR-SERVER:8080 \
  -e TROVE_TOKEN=AGENT_TOKEN_VALUE \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  ghcr.io/techdox/trove-agent-docker:latest

Configuration

Variable	Default	Purpose
TROVE_SERVER_URL	required	Base URL of the Trove server.
TROVE_TOKEN	required	Trove agent token.
TROVE_INTERVAL	30s	Push interval.
TROVE_AGENT_NAME	hostname	Informational report name. The dashboard agent name comes from agent create.
DOCKER_HOST	unix:///var/run/docker.sock	Docker endpoint.

Docker socket access

The agent normally mounts:

/var/run/docker.sock:/var/run/docker.sock:ro

The Docker socket is sensitive even when mounted read-only. Treat this agent as trusted code.

The agent itself is designed to use GET-only Docker Engine API calls. It does not create, stop, restart, remove, or exec into containers.

Health mapping

Docker health maps into Trove health like this:

Docker condition	Trove health
container has healthcheck and reports healthy	healthy
container has healthcheck and reports unhealthy	unhealthy
running container without healthcheck	unknown
exited container with restart policy always or unless-stopped	unhealthy
exited container without persistent restart policy	unknown

The state field still carries the Docker state, so stopped/exited containers remain visible.

For unhealthy containers, Trove also reports a short health_detail: the latest failing Docker healthcheck output and exit code, or the container exit code/daemon error when a container stopped despite an always or unless-stopped restart policy.

The host header includes Docker Engine version, API version, OS, and architecture when the daemon exposes them.

Compose labels

Docker Compose labels are included in the service labels. The dashboard can use these to group or identify services from Compose projects.

Troubleshooting

Agent connects but no containers show

Check the socket mount and Docker endpoint:

docker logs trove-agent-docker

If the agent cannot talk to Docker, collection fails before pushing.

Push failed with 401

The TROVE_TOKEN does not match an agent token in the server database.

Create a new token:

docker compose exec server trove-server agent create docker-nuc01

Then update the agent container.

Server URL mistake

If the server is not on the same host/container namespace, do not use localhost.

Use the server's LAN IP, DNS name, or reverse proxy address.