compose.yaml

services:
  ecaa:
    image: ${ECAA_IMAGE:-ecaa-workflow-server:local}
    init: true
    # Host networking so the server binds the HOST's loopback directly. That makes
    # it a genuine 127.0.0.1 bind, which the server treats as trusted-local: no
    # ECAA_SERVER_AUTH_TOKEN required and the full /api works with zero friction —
    # exactly like running the binary on the host. (Port-publishing instead forces a
    # 0.0.0.0 container bind, which the server hard-requires a bearer token for, and
    # the browser UI does not send one.) Linux: works as-is. macOS/Windows Docker
    # Desktop: host networking is limited — see deploy/README.md for the alternative.
    network_mode: host
    user: "${ECAA_UID}:${ECAA_GID}"
    group_add:
      - "${DOCKER_GID:-0}"            # read the mounted docker socket (docker path)
    environment:
      HOME: "${HOME}"
      ECAA_BIND_ADDR: "127.0.0.1"     # loopback on the host => trusted-local, no token
      ECAA_CONFIG_DIR: "/app/config"
      ECAA_PACKAGE_ROOT: "${HOME}/.ecaa-workflow/packages"
      ECAA_CHAT_SESSIONS_DIR: "${HOME}/.ecaa-workflow/sessions"
      ECAA_AGENT_HOME_DIR: "${HOME}/.ecaa-workflow/agent-home"   # OUTSIDE the package tree
      # Writable cache for the per-session claude-code CLI install + agent HOME.
      # Container HOME (/home/<you>) is NOT writable — only ~/.ecaa-workflow and
      # ~/.claude are bind-mounted rw — so without this the CLI npm-install lands
      # in a read-only path and the agent silently returns empty responses.
      ECAA_SESSION_CACHE_DIR: "${HOME}/.ecaa-workflow/session-cache"
      # npm cache in a writable mount too — HOME/.npm defaults under the
      # non-writable /home/<you>, which makes the per-session claude-code
      # `npm install` fail and forces slow/fragile per-sibling npx downloads.
      npm_config_cache: "${HOME}/.ecaa-workflow/session-cache/npm-cache"
      # Local trusted single-user deployment: let the agent subprocess inherit
      # the full harness env instead of the env_clear allowlist. The allowlist
      # omits several vars the containerized claude CLI needs (subscription
      # token, session cache, npm cache, and more), which silently yields empty
      # agent responses in this compose path. Safe here (loopback, one operator,
      # public data); do NOT set on a shared/multi-tenant server.
      ECAA_DISABLE_ENV_CLEAR: "1"
      # Serialize agent dispatch (one agent at a time) so concurrent Claude Code
      # sessions don't trip the subscription's short-window burst limit.
      ECAA_HARNESS_CONCURRENCY: "1"
      ECAA_HARNESS_VALIDATION_LANE: "0"
      ECAA_HARNESS_BIN_PATH: "/usr/local/bin/ecaa-workflow-harness"
    env_file:
      - .env
    volumes:
      - "${ECAA_DOCKER_SOCK:-/var/run/docker.sock}:/var/run/docker.sock"
      - "${HOME}/.ecaa-workflow:${HOME}/.ecaa-workflow"          # state at IDENTICAL host path
      - "${HOME}/.claude:${HOME}/.claude:ro"                     # subscription creds, read-only
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/healthz"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 30s