docker-compose.yml

name: cortex

# Local development stack. Builds from this checkout.
services:
  cortex:
    build:
      context: .
      dockerfile: config/Dockerfile
    container_name: cortex
    user: "${CORTEX_UID:-1000}:${CORTEX_GID:-1000}"
    group_add:
      # Lets the non-root cortex user read common /var/log files such as
      # auth.log/syslog when CORTEX_FILE_TAIL_LOG_VOLUME defaults to /var/log.
      # Set to a numeric host group id if your log-reader group is not adm.
      - "${CORTEX_FILE_TAIL_GROUP:-adm}"
    env_file:
      - path: ${CORTEX_ENV_FILE:-.env}
        required: false
    environment:
      # CORTEX_PORT in .env selects the host publication; internal port is fixed.
      CORTEX_PORT: "3100"
      CORTEX_HOME: /cortex-home
      CORTEX_GRAPH_REFRESH_INTERVAL_SECS: "${CORTEX_GRAPH_REFRESH_INTERVAL_SECS:-300}"
      CORTEX_INVENTORY_GRAPH_PROJECTION_ENABLED: "${CORTEX_INVENTORY_GRAPH_PROJECTION_ENABLED:-true}"
      # Accept the Host header used by the Labby gateway when it proxies this
      # service over the docker network (http://cortex:3100/mcp). Without this,
      # RMCP Host validation rejects gateway calls with "Host header is not allowed".
      CORTEX_ALLOWED_HOSTS: "cortex,cortex:3100,${CORTEX_ALLOWED_HOSTS:-}"
    ports:
      # Syslog ingestion must be reachable by remote forwarders — published wide.
      # Restrict senders with CORTEX_ALLOWED_SOURCE_CIDRS if needed.
      - "${CORTEX_RECEIVER_HOST_PORT:-1514}:${CORTEX_RECEIVER_PORT:-1514}/udp"
      - "${CORTEX_RECEIVER_HOST_PORT:-1514}:${CORTEX_RECEIVER_PORT:-1514}/tcp"
      # MCP/API is unauthenticated by default, so it binds loopback by default.
      # The Labby gateway reaches it over the docker network (http://cortex:3100)
      # and needs no host publishing at all. To expose on the LAN deliberately,
      # set CORTEX_MCP_BIND=0.0.0.0 (or a specific interface IP) AND set
      # CORTEX_TOKEN so the exposed endpoint requires auth.
      - "${CORTEX_MCP_BIND:-127.0.0.1}:${CORTEX_PORT:-3100}:3100/tcp"
    volumes:
      - ${CORTEX_HOME_VOLUME:-${HOME}/.cortex}:/cortex-home
      # SSH identity for fleet inventory collection. Defaults to a DEDICATED
      # key directory (~/.cortex/ssh) — provision it with a least-privilege
      # deploy key + known_hosts. Do NOT point this at ~/.ssh: any container
      # compromise could read your personal private keys and pivot across the
      # fleet (full-review SM2). Set CORTEX_SSH_VOLUME to override.
      - ${CORTEX_SSH_VOLUME:-${HOME}/.cortex/ssh}:/home/cortex/.ssh:ro
      - ${CORTEX_WORKSPACE_VOLUME:-${HOME}/workspace}:/home/cortex/workspace:ro
      - ${CORTEX_DATA_VOLUME:-cortex-data}:/data
      # Backups must live outside the data volume so volume loss does not take
      # both the database and its recovery copy.
      - type: bind
        source: ${CORTEX_BACKUP_DIR:-${HOME}/.cortex/backups}
        target: /backups
        bind:
          create_host_path: false
      # Managed file-tail ingest can only read paths mounted under this root.
      # Point CORTEX_FILE_TAIL_LOG_VOLUME at /var/log, /mnt/user/appdata, or a
      # narrower log directory. Keep it read-only.
      - ${CORTEX_FILE_TAIL_LOG_VOLUME:-/var/log}:/file-tail-root:ro
    networks:
      - cortex
    restart: unless-stopped
    extra_hosts:
      - "host.docker.internal:host-gateway"
      # Optional fleet aliases belong in a deployment-local Compose override.
      # Do not put synthetic documentation addresses in active routing config.
    ulimits:
      nofile:
        soft: 65535
        hard: 65535
    logging:
      driver: "json-file"
      options:
        # Overrides the shared anchor. Cortex's own stderr is the only record
        # of why cortex itself misbehaved: it is never self-ingested into
        # SQLite (src/agent/docker.rs refuses to forward the `cortex`
        # container), so `retention_days` does not cover it and this ring is
        # its entire lifetime.
        #
        # Size it for forensics, not for a quiet service. The volume spikes
        # exactly during an incident, so a ring tuned for idle throughput
        # collapses to minutes at the moment the logs matter most — the
        # shared 30 MB default lost the history during the 2026-08-24 pool
        # contention investigation.
        max-size: "${CORTEX_LOG_MAX_SIZE:-200m}"
        max-file: "${CORTEX_LOG_MAX_FILE:-10}"
        compress: "true"
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:3100/health || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    deploy:
      resources:
        limits:
          # Parity with docker-compose.prod.yml: 512M previously triggered OOM
          # restarts under heavy stats/sessions aggregations (full-review OM7).
          # Tune per-host via CORTEX_MEMORY_LIMIT / CORTEX_CPU_LIMIT.
          memory: ${CORTEX_MEMORY_LIMIT:-2G}
          cpus: '${CORTEX_CPU_LIMIT:-1.0}'

volumes:
  cortex-data:
    name: ${CORTEX_VOLUME_NAME:-cortex-data}

networks:
  cortex:
    name: ${DOCKER_NETWORK:-cortex}
    external: true