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.

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