Docker Compose Deployment

Docker Compose is the recommended way to run Agentcy locally or on a single server. It starts all required services with one command.

Prerequisites

• Docker Engine 24+ with Docker Compose v2
• At least 4 GB of available RAM
• An LLM API key (Anthropic or OpenAI)

Quick Start

Agentcy is closed-source software. To get a copy of the release tarball for an in-house deployment, request access via agentcylabs.com. After unpacking it:

cd agentcy
cp .env.example .env
# Edit .env with your LLM API key
docker compose up -d

The frontend is available at http://localhost:3000 and the API at http://localhost:8080.

Services

The docker-compose.yml defines six services:

Core Services

Service	Image	Port	Description
backend	ghcr.io/agentcy/backend	8080	Rust/Axum API server (agentcy-api binary)
frontend	ghcr.io/agentcy/frontend	3000	Next.js 16 web application

Infrastructure

Service	Image	Port	Description
postgres	postgres:16-alpine	15432	Primary relational data store
neo4j	neo4j:5-community	17474 / 17687	Knowledge graph (HTTP / Bolt)
redis	redis:7-alpine	16379	Job queues and caching

Optional

Service	Image	Port	Description
openfang	ghcr.io/agentcy/openfang	8081	Agent orchestration sidecar

To start with OpenFang:

docker compose --profile subagents up -d

docker-compose.yml Walkthrough

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: agentcy
      POSTGRES_USER: agentcy
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-agentcy}
    ports:
      - "15432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U agentcy"]
      interval: 5s
      timeout: 3s
      retries: 5

  neo4j:
    image: neo4j:5-community
    environment:
      NEO4J_AUTH: neo4j/${NEO4J_PASSWORD:-agentcy}
      NEO4J_PLUGINS: '["apoc"]'
    ports:
      - "17474:7474"
      - "17687:7687"
    volumes:
      - neo4jdata:/data

  redis:
    image: redis:7-alpine
    ports:
      - "16379:6379"
    volumes:
      - redisdata:/data

  backend:
    image: ghcr.io/agentcy/backend:latest
    ports:
      - "8080:8080"
    env_file: .env
    environment:
      DATABASE_URL: postgres://agentcy:${POSTGRES_PASSWORD:-agentcy}@postgres:5432/agentcy
      NEO4J_URI: bolt://neo4j:7687
      NEO4J_USER: neo4j
      NEO4J_PASSWORD: ${NEO4J_PASSWORD:-agentcy}
      REDIS_URL: redis://redis:6379
    depends_on:
      postgres:
        condition: service_healthy
      neo4j:
        condition: service_started
      redis:
        condition: service_started

  frontend:
    image: ghcr.io/agentcy/frontend:latest
    ports:
      - "3000:3000"
    environment:
      NEXT_PUBLIC_API_URL: http://backend:8080/api/v1

  openfang:
    image: ghcr.io/agentcy/openfang:latest
    ports:
      - "8081:8081"
    profiles:
      - subagents
    environment:
      DATABASE_URL: postgres://agentcy:${POSTGRES_PASSWORD:-agentcy}@postgres:5432/agentcy

volumes:
  pgdata:
  neo4jdata:
  redisdata:

Environment Variables

Create a .env file from the example:

cp .env.example .env

Required

Variable	Description	Example
LLM_API_KEY	Anthropic or OpenAI API key	sk-ant-...
LLM_PROVIDER	LLM provider to use	anthropic or openai

Database (defaults work for Docker Compose)

Variable	Default	Description
POSTGRES_PASSWORD	agentcy	PostgreSQL password
NEO4J_PASSWORD	agentcy	Neo4j password
DATABASE_URL	(set in compose)	Full PostgreSQL connection string
NEO4J_URI	(set in compose)	Neo4j Bolt URI
REDIS_URL	(set in compose)	Redis connection string

Authentication

Variable	Default	Description
AUTH_PROVIDER	local	local for built-in auth, oidc for SSO
JWT_SECRET	(auto-generated)	Secret for signing local JWTs
JWKS_URL	—	JWKS endpoint for OIDC provider
JWT_AUDIENCE	—	Expected JWT audience claim
JWT_ISSUER	—	Expected JWT issuer claim

Optional

Variable	Default	Description
OPENFANG_URL	http://openfang:8081	OpenFang sidecar URL
LOG_LEVEL	info	Logging level (debug, info, warn, error)
CORS_ORIGINS	http://localhost:3000	Comma-separated allowed origins

Volume Mounts

Three named volumes persist data across container restarts:

Volume	Mounted At	Contents
pgdata	/var/lib/postgresql/data	All relational data (users, connectors, conversations, policies)
neo4jdata	/data	Knowledge graph nodes and relationships
redisdata	/data	Redis RDB snapshots

Backup Strategy

Named volumes are not backed up automatically. Set up periodic backups:

# PostgreSQL dump
docker compose exec postgres pg_dump -U agentcy agentcy > backup.sql

# Neo4j dump (stop neo4j first)
docker compose stop neo4j
docker run --rm -v agentcy_neo4jdata:/data -v $(pwd):/backup \
  neo4j:5-community neo4j-admin database dump neo4j --to-path=/backup/
docker compose start neo4j

Production Hardening

For production deployments, add these configurations:

Resource Limits

services:
  backend:
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 2G
        reservations:
          cpus: "0.5"
          memory: 512M

  postgres:
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 1G

  neo4j:
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 4G

Restart Policies

services:
  backend:
    restart: unless-stopped
  frontend:
    restart: unless-stopped
  postgres:
    restart: unless-stopped
  neo4j:
    restart: unless-stopped
  redis:
    restart: unless-stopped

Security

• Change all default passwords in .env
• Set CORS_ORIGINS to your actual domain
• Put a reverse proxy (Nginx, Caddy, Traefik) in front for TLS termination
• Restrict exposed ports — only the frontend (3000) and backend (8080) need external access
• Remove port mappings for postgres, neo4j, and redis in production

Reverse Proxy Example (Caddy)

services:
  caddy:
    image: caddy:2-alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data

# Caddyfile
agentcy.example.com {
    handle /api/* {
        reverse_proxy backend:8080
    }
    handle {
        reverse_proxy frontend:3000
    }
}

Updating

Pull the latest images and restart:

docker compose pull
docker compose up -d

The backend runs database migrations automatically on startup. No manual migration step is needed.

Troubleshooting

Backend fails to start

Check that PostgreSQL is healthy before the backend starts:

docker compose logs postgres
docker compose logs backend

Neo4j out of memory

Increase the Neo4j memory limit and configure heap:

neo4j:
  environment:
    NEO4J_server_memory_heap_max__size: "2G"
    NEO4J_server_memory_pagecache_size: "1G"

Port conflicts

If ports 15432, 17687, or 16379 conflict with existing services, change the host-side port mappings in docker-compose.yml. The internal container ports must stay the same.