Docker Agent

The Docker Compose agent manages container-based deployments, handling both single- and multi-container applications. It performs application updates with minimal downtime, collects container health metrics and logs, and supports environment variable templating for flexible configuration.

Note

Unless you’re using Distr to deploy your own applications internally, the Distr agent will always be configured and deployed by the end customer. Head over to the end-customer agent guide to learn how it should be installed.

Requirements

The host system must have Docker and Docker Compose installed.

Installation and Environment

The agent is installed by running a single command that fetches a Docker Compose file from the Distr Hub and starts it:

curl "https://<distr-hub>/api/v1/connect?targetId=<targetId>&targetSecret=<targetSecret>" | docker compose -f - up -d

The targetId and targetSecret ensure the agent can only fetch deployments for one specific deployment target. The secret is shown once and never stored by the Hub — it can only be verified.

The fetched Compose file runs the agent container:

name: distr
services:
  agent:
    network_mode: host
    restart: unless-stopped
    image: 'ghcr.io/distr-sh/distr/docker-agent'
    environment:
      # Authentication with Distr Hub, see above
      DISTR_TARGET_ID: '<targetId>'
      DISTR_TARGET_SECRET: '<targetSecret>'
      # various endpoints of the Distr Hub:
      DISTR_LOGIN_ENDPOINT: 'https://<distr-hub>/api/v1/agent/login'
      DISTR_MANIFEST_ENDPOINT: 'https://<distr-hub>/api/v1/agent/manifest'
      DISTR_RESOURCE_ENDPOINT: 'https://<distr-hub>/api/v1/agent/resources'
      DISTR_STATUS_ENDPOINT: 'https://<distr-hub>/api/v1/agent/status'
      DISTR_METRICS_ENDPOINT: 'https://<distr-hub>/api/v1/agent/metrics'
      # how often the agent fetches deployments
      DISTR_INTERVAL: '5s'
      # agent versioning information, needed for agent self-updates:
      DISTR_AGENT_VERSION_ID: '<db-id-of-agent-version>'
      DISTR_AGENT_SCRATCH_DIR: /scratch
      DISTR_REGISTRY_HOST: 'localhost:8585'
      HOST_DOCKER_CONFIG_DIR: ${HOST_DOCKER_CONFIG_DIR-${HOME}/.docker}
    volumes:
      # the host's docker socket is mounted into the agent container
      - /var/run/docker.sock:/var/run/docker.sock
      - scratch:/scratch
      - ${HOST_DOCKER_CONFIG_DIR-${HOME}/.docker}:/root/.docker:ro
volumes:
  scratch:

All requests to the Distr Hub are authenticated with a JWT token obtained by calling DISTR_LOGIN_ENDPOINT with the targetId and targetSecret credentials. The Docker socket is mounted so the agent can manage containers on the host.

Core Logic

The agent runs the following loop at the interval defined by DISTR_INTERVAL (default 5 seconds):

1. Fetch the deployments from DISTR_RESOURCE_ENDPOINT
2. Delete Docker Compose projects that are no longer in the list (undeployed), with docker compose down -v
3. Start Docker Compose projects that are in the list, with docker compose up -d. Environment variables are passed via --env-file. If images need pulling, the agent reports status PROGRESSING.
4. Send each Docker Compose output to DISTR_STATUS_ENDPOINT, reporting the deployment’s status.

Each deployment maps to one Docker Compose project on the host, named distr-<short-deployment-id>.

Authentication with OCI Registries

If a deployment uses images from the Distr registry, the agent authenticates automatically — no extra steps needed for the customer. The authentication secret is stored in a temporary directory inside the agent container.

For any other authenticated OCI registry, the agent mounts the host’s Docker config directory so existing credentials are reused. Any registry accessible from the host is also accessible to the agent.

You can also provide credentials via an application entitlement (Pro feature). When a deployment is created with that entitlement, the agent logs in to the specified registry using the provided credentials.

Agent Self Updates

When the agent version for a deployment target is updated in the Distr Hub, the agent updates itself on the next cycle. It fetches the new manifest from DISTR_MANIFEST_ENDPOINT and restarts. The DISTR_AGENT_SCRATCH_DIR environment variable and scratch volume mount are required for this to work.

Autoheal

Distr deploys an autoheal service alongside every Docker agent. This service monitors container health and automatically restarts containers that become unhealthy.

When autoheal is enabled for all containers, the underlying docker-autoheal service targets every unhealthy container visible to the Docker engine on that host, not just containers from a specific Distr deployment. This means your application containers are automatically restarted if they fail their healthchecks. For this to work, your application must define Docker healthchecks in its Compose file. Containers without healthchecks are not monitored.

The autoheal setting is configured when creating a deployment target. In the deployment wizard, the Enable autoheal for all containers checkbox is enabled by default for Docker deployments. When disabled, the autoheal service still runs but only monitors the Distr agent itself. To prevent unrelated containers on the same host from being auto-healed, label those containers with autoheal=False.

Note

Autoheal is only available for Docker deployments. This setting can only be configured during deployment target creation and cannot be changed afterward. To change it, delete the deployment target and create a new one.

Image Cleanup

By default, when the agent updates a deployment to a new version, the previous container images remain on the host. Over time this can consume significant disk space.

When Enable container image cleanup is checked, the agent automatically removes the previous version’s container images after a successful deployment update. This setting is enabled by default for new Docker deployment targets.

To toggle image cleanup on an existing deployment target:

1. Navigate to the deployment target in the Deployments view.
2. Click the ⋮ menu and select Edit.
3. Toggle Enable container image cleanup.

Image cleanup only runs after a successful update. If a deployment fails, the previous images are kept so a rollback remains possible.

Note

Image cleanup is only available for Docker deployments.

Docker Swarm

A deployment can run in Swarm mode. The host must have Docker Swarm enabled and initialized. Instead of docker compose up, the agent uses docker stack deploy. Unlike regular Compose mode, docker stack deploy is only called when the deployment has changed, not on every cycle.

Uninstalling

Before removing the agent, undeploy all managed deployments via the UI or API.

Then stop and remove the agent container:

docker stop distr-agent-1 && docker rm distr-agent-1