System configuration

In this page

Three parts of the stack take more than a key or two in .env: the LLM gateway, which routes the platform’s model calls; PeerDB, which copies Postgres changes into ClickHouse on Distributed; and the Temporal workers that run background jobs. Where each one runs, and what you can change, depends on the setup. The keys named here are set as described in Environment variables.

LLM gateway

The gateway is a Go proxy that routes the model calls the platform makes. It also serves an OpenAI-compatible endpoint that your own apps can call, on http://localhost:8090 (AGENTCC_GATEWAY_PORT) in both Compose setups.

Set a provider key in .env (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY or the AWS pair) and run docker compose up -d. One provider is enough to start, and workspaces can also add their own keys in the UI.

The gateway’s bundled config, agentcc-gateway/config.example.yaml, routes OpenAI. To route more providers through it:

cp agentcc-gateway/config.example.yaml agentcc-gateway/config.yaml

AGENTCC_CONFIG_PATH=agentcc-gateway/config.yaml

ANTHROPIC_API_KEY=sk-...

docker compose up -d
curl -sf http://localhost:8090/healthz

On Helm, the gateway’s config is the chart value agentccGateway.config, and provider keys come from secrets.llm. See Configure.

Provider examples

The models lists below are examples: list the models your provider account serves.

providers:
  openai:
    base_url: "https://api.openai.com"
    api_key: "${OPENAI_API_KEY}"
    api_format: "openai"
    models: [gpt-4o, gpt-4o-mini]

  anthropic:
    base_url: "https://api.anthropic.com"
    api_key: "${ANTHROPIC_API_KEY}"
    api_format: "anthropic"
    models: [claude-sonnet-4-6, claude-opus-4-7]

  gemini:
    base_url: "https://generativelanguage.googleapis.com"
    api_key: "${GEMINI_API_KEY}"
    api_format: "gemini"
    models: [gemini-3.5-flash, gemini-3.5-flash-lite]

providers:
  bedrock:
    base_url: "https://bedrock-runtime.us-east-1.amazonaws.com"
    api_format: "bedrock"
    aws_access_key_id: "${AWS_ACCESS_KEY_ID}"
    aws_secret_access_key: "${AWS_SECRET_ACCESS_KEY}"
    aws_region: "us-east-1"
    models: [us.anthropic.claude-sonnet-4-6]

providers:
  vertex:
    base_url: "https://aiplatform.googleapis.com"
    api_format: "gemini"
    credentials_file: "${GOOGLE_APPLICATION_CREDENTIALS}"
    headers:
      x-gcp-project: "${GCP_PROJECT_ID}"
      x-gcp-location: "global"
    models: [gemini-3.5-flash]

For routing rules, rate limits, caching and the full config reference, see Self-hosted deployment.

Local and private model servers

A model server such as Ollama or vLLM that you list under providers: in the gateway’s config.yaml needs nothing more: those entries are trusted, have no address check, and serve the platform’s own calls. One that a workspace adds in the UI under Gateway > Providers, on a private address such as host.docker.internal or a Docker service name, needs AGENTCC_ALLOW_PRIVATE_PROVIDER_URLS=true (Helm: agentccGateway.allowPrivateProviderURLs=true): Private and local provider URLs has the steps, Linux hosts, the risks and the errors you may see.

Keys and org settings sync

The gateway loads the API keys and organization settings created in the UI from the app. It starts serving at once with the keys in its config.yaml, loads the rest in the background, retrying until the app answers, and then re-reads them every AGENTCC_SYNC_INTERVAL: 60s in both compose files, and on Helm the same through agentccGateway.config.control_plane.sync_interval. Its log shows control plane startup sync succeeded once the first load works, and the control plane sync enabled line shows the interval it runs with.

Sync on Gateway > API Keys pushes the organization’s live keys that the gateway lacks, and revokes on the gateway any key that was revoked while the gateway could not be reached.

PeerDB replication

Only Distributed runs PeerDB. It copies Postgres changes into ClickHouse, the analytics store behind traces, dashboards and evaluation queries. Standalone and Helm use capture triggers drained by a Temporal schedule instead, so neither runs PeerDB. On Standalone the drain runs in the API process, with the embedded Temporal worker; on Helm, in the all-queues worker Deployment.

On Distributed, the PeerDB services start with the stack whatever the profile, and one-shot jobs set up the peers and mirrors on first boot: peerdb-init runs once the Postgres and ClickHouse schema jobs have finished, and clickhouse-cdc-bootstrap waits for the mirrors before the backend starts.

The PeerDB UI comes with the peerdb or all profile, on http://localhost:3001 (PEERDB_UI_PORT). The installer’s summary lists its login, peerdb / peerdb.

services:
  peerdb-ui:
    ports: !override
      - "127.0.0.1:${PEERDB_UI_PORT:-3001}:3000"
  temporal-ui:
    ports: !override
      - "127.0.0.1:${TEMPORAL_UI_PORT:-8085}:8080"

PeerDB’s init job stores CH_PASSWORD in its ch_dest peer when it creates it. A later change to CH_PASSWORD stops the sync until that peer carries the new password: see Secrets the installer generates.

Temporal workers

Temporal runs the platform’s background work: evaluations, optimizations, scheduled jobs and, on Standalone and Helm, the Postgres to ClickHouse sync.

Standalone

Standalone runs a Temporal dev server on SQLite inside the app container, without its web UI, and the worker runs inside the API process. It polls every queue except the simulation runner’s, with these slots per queue:

Standalone ignores TEMPORAL_MAX_CONCURRENT_ACTIVITIES and TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASKS. Its Temporal server keeps 32 schedules busy, six of which fire every 10 seconds, and the API shares its process with the worker, so a host short of CPU slows both. For more concurrent users or a steady eval load, use Distributed: see Choose a setup.

Distributed

Two workers always run:

• worker polls every queue except the exact-aggregation queue and those in TEMPORAL_EXCLUDED_QUEUES (default simulation_runner), while TEMPORAL_ALL_QUEUES=true, the default. Its slots are TEMPORAL_MAX_CONCURRENT_ACTIVITIES and TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASKS, 50 each.
• worker-exact-aggregation serves the exact-analytics queue with a single slot.

The workers (or all) profile adds one worker per queue. Set TEMPORAL_ALL_QUEUES=false with it, so that worker polls only the default queue instead of every queue alongside them. Never set it without workers or all: the other queues would then have no worker. Add both lines to .env, then run docker compose up -d:

COMPOSE_PROFILES=workers
TEMPORAL_ALL_QUEUES=false

worker-simulation-runner runs its own image, futureagi/future-agi-simulation-runner, for hosted voice simulations, and workers and all always start it. That image is linux/amd64 only: on an arm64 host, such as Apple Silicon or AWS Graviton, Docker runs it under emulation, which on Linux needs qemu-user-static. See Per-queue workers.

The observability or all profile adds the Temporal UI on http://localhost:8085 (TEMPORAL_UI_PORT) and the temporal-admin-tools container. The Temporal UI has no sign-in: see the warning under PeerDB replication.

Helm

worker.allQueues is the all-queues worker, with maxConcurrentActivities and maxConcurrentWorkflowTasks of 50 each. Each worker.queues entry gives a busy queue its own Deployment, which the all-queues worker then stops polling. See Configure.

Dive deeper