Multi-container

Multi-container documentation for Harbor.

Multi-container environments enable additional services to your environment to represent databases, APIs, MCPs, etc.

Specification

In most cases, use environment/docker-compose.yaml to specify the multi-container environment.

Harbor itself is agnostic to which infra-as-code spec you use, which means it is possible to support multi-container environments using something other than docker-compose.yaml. We have not implemented support for anything else natively, but users are free to do so by implementing a custom environment.

Reserved services and default compose

Harbor reserves the main service name for the agent container. All other services are treated as sidecars. Harbor merges your environment/docker-compose.yaml on top of a base compose file, so you do not need to define the main service build or keepalive command yourself.

For tasks with a Dockerfile, the base compose is docker-compose-build.yaml:

src/harbor/environments/docker/docker-compose-build.yaml

services:
  main:
    build:
      context: ${CONTEXT_DIR}
    pull_policy: build
    command: [ "sh", "-c", "sleep infinity" ]

For tasks that use a prebuilt image instead of building locally, Harbor uses docker-compose-prebuilt.yaml:

src/harbor/environments/docker/docker-compose-prebuilt.yaml

services:
  main:
    image: ${PREBUILT_IMAGE_NAME}
    command: [ "sh", "-c", "sleep infinity" ]

Example Layout

my-task/
├── instruction.md
├── task.toml
└── environment/
    ├── Dockerfile              # agent (main) service
    ├── docker-compose.yaml     # sidecars + depends_on
    └── mcp-server/             # optional service build context
        ├── Dockerfile
        └── server.py

Harbor treats the agent service as main. In compose you typically only add overrides such as depends_on and healthchecks; Harbor wires the rest.

environment/docker-compose.yaml

services:
  main:
    depends_on:
      mcp-server:
        condition: service_healthy

  mcp-server:
    build:
      context: ./mcp-server
    expose:
      - "8000"
    healthcheck:
      test: ["CMD", "python", "-c", "import socket; s=socket.create_connection(('localhost',8000),timeout=2); s.close()"]
      interval: 2s
      timeout: 5s
      retries: 15
      start_period: 5s

Sidecars share a Docker network with main; reach them by service name (e.g. http://mcp-server:8000).

Support

Support	Environments
Native Compose	docker, podman, ec2, islo, vercel
DinD Docker Compose	blaxel, beam, daytona, gke, hyperbrowser, langsmith, modal, novita, tensorlake
Other multi-container specifications	Custom environments only
Not supported	e2b, runloop, ack, openshift, apple-container, singularity, cwsandbox, wandb, use-computer, cua-cloud, opensandbox, skypilot, hf-sandbox