Docker

The Docker Host is the machine that runs Docker bots. It runs the Docker Host agent: a container that connects to the Sinfonia orchestrator, receives executions from the queue, fetches the bot image and runs it as a container on the machine’s own Docker.

This agent is different from the agents for Windows and Linux, used by Script, Zip and Git bots. Docker bots can only run on a Docker Host. They are compared in the Agents overview.

How it works

    flowchart LR
    O["Sinfonia<br/>orchestrator"] <-->|HTTPS| A["Docker Host<br/>agent"]
    A -->|docker.sock| D["Host's<br/>Docker Engine"]
    D --> C["Bot<br/>container"]
    R[("Registry or<br/>image file")] -->|image| D
  

1. The agent polls the orchestrator’s execution queue.
2. When it receives an execution, it checks whether the bot image already exists on the host. If not, it fetches the image according to the source configured in the bot: pull from a public registry, authenticated pull, or load of the uploaded file.
3. It creates and starts the container, passing along the execution’s environment variables.
4. It captures the container output (stdout and stderr) and sends it to the orchestrator as the execution log.
5. At the end, it removes the container and records the result: exit code 0 means success, any other value means error.

Requirements

• Linux machine with Docker Engine and the Docker Compose plugin installed.
• Docker Host feature purchased on the platform.
• Outbound access to the Sinfonia orchestrator at grpc.sinfonia.live over HTTPS (port 443), as described in the prerequisites.
• Outbound access to the registries the bot images will be pulled from (Docker Hub, GHCR, Amazon ECR, etc.).
• UDP ports 49252 to 49292 allowed through the firewall to the host, used to view container logs in real time from the portal.
• An agent token. Use the account’s master token or create a new one in tokens.
• Enough CPU, memory and disk for the agent and for the bot containers that will run on the host.

Deployment

docker load --input <image-file>

services:
  sinfonia-docker-host:
    image: <name>:<tag>
    container_name: sinfonia-docker-host
    restart: unless-stopped
    environment:
      AGENT_NAME: DOCKER-HOST-01
      AGENT_TOKEN: <your-token>
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/rootfs:ro
      - /etc/os-release:/etc/os-release:ro
    ports:
      - 49252-49292:49252-49292/udp
    deploy:
      resources:
        limits:
          cpus: "2"
          memory: "2000MB"

cd /opt/sinfonia-docker-host
docker compose up -d

docker logs -f sinfonia-docker-host

Managing images and containers

On the portal’s Docker Hosts screen you can follow each connected host, with its stored images and existing containers, and you can:

• view a container’s logs;
• start, pause, restart, stop, kill or remove a container;
• remove an image from the host.

Execution behavior

• Start time: with an empty queue, the agent polls the orchestrator every 30 seconds. An execution may take up to that long to start.
• Image cache: the agent only fetches the image when it does not yet exist on the host. If you publish new content reusing the same tag (for example latest), the host keeps running the old image.
• Cleanup: the container is removed at the end of each execution. The image stays on the host for subsequent executions.

Updating or removing the agent

To update, download the new version of the image from the platform, load it on the host and recreate the container:

docker load --input <image-file>
docker compose up -d

If the new image has a different tag, update the image field in docker-compose.yml before recreating the container.

To remove the agent from the host:

docker compose down

Troubleshooting

Next step