From 83ae3ab19f7db591877a0046d18c9e9166610c37 Mon Sep 17 00:00:00 2001 From: Abhijai Srivastava Date: Mon, 29 Jun 2026 20:03:36 +0530 Subject: [PATCH 1/4] docs: add self-hosting system configuration page TH-6328 --- .../self-hosting/configuration/system.mdx | 143 ++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 src/pages/docs/self-hosting/configuration/system.mdx diff --git a/src/pages/docs/self-hosting/configuration/system.mdx b/src/pages/docs/self-hosting/configuration/system.mdx new file mode 100644 index 00000000..11be1545 --- /dev/null +++ b/src/pages/docs/self-hosting/configuration/system.mdx @@ -0,0 +1,143 @@ +--- +title: "System Configuration" +description: "Configure the moving parts beyond .env — the LLM gateway config.yaml with provider keys, PeerDB Postgres-to-ClickHouse replication mirrors, and Temporal worker concurrency." +--- + +## Introduction + +A few parts of the stack are configured outside `.env`: the LLM gateway needs a `config.yaml` listing its providers, PeerDB needs its replication mirrors running, and Temporal workers can be tuned for throughput. This page covers all three. Set your secrets and provider keys in [Environment Variables](/docs/self-hosting/configuration/environment) first — the config here references them. + +## LLM Gateway + +The gateway is a Go proxy that routes every model call the platform makes. It reads a `config.yaml` that lists which providers it may use and which models each exposes. + + +Model calls fail until this file exists. The gateway ships with `config.example.yaml` (OpenAI enabled) but **not** a live `config.yaml` — you create one in the steps below. + + + + +```bash +cp futureagi/agentcc-gateway/config.example.yaml \ + futureagi/agentcc-gateway/config.yaml +``` + + + +Edit `config.yaml` — uncomment the providers you want and reference their keys with `${VAR}` interpolation. Set the matching keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, …) in `.env`. See the provider examples below. + + + +Point the gateway volume at your `config.yaml` in `docker-compose.yml`: + +```yaml +volumes: + - ./futureagi/agentcc-gateway/config.yaml:/app/config.yaml:ro +``` + +```bash +docker compose up -d --force-recreate gateway +``` + + + + +`config.yaml` is gitignored and holds live API keys. Treat it as a secret — never commit it. + + +### Provider Examples + + + +```yaml +providers: + openai: + api_key: "${OPENAI_API_KEY}" + api_format: "openai" + models: [gpt-4o, gpt-4o-mini] + + anthropic: + api_key: "${ANTHROPIC_API_KEY}" + api_format: "anthropic" + models: [claude-opus-4-5, claude-sonnet-4-5] + + gemini: + api_key: "${GOOGLE_API_KEY}" + api_format: "gemini" + models: [gemini-2.0-flash, gemini-1.5-pro] +``` + + +```yaml +providers: + bedrock: + api_key: "${AWS_SECRET_ACCESS_KEY}" + api_format: "bedrock" + region: "${AWS_REGION}" + access_key: "${AWS_ACCESS_KEY_ID}" + models: [anthropic.claude-3-5-sonnet-20241022-v2:0] +``` + + +```yaml +providers: + vertex: + base_url: "https://us-central1-aiplatform.googleapis.com" + api_key: "${GOOGLE_ACCESS_TOKEN}" + api_format: "gemini" + headers: + x-gcp-project: "${GCP_PROJECT_ID}" + x-gcp-location: "us-central1" + models: [gemini-2.0-flash-001] +``` + +Vertex uses a Bearer token, not a static API key. Rotate `GOOGLE_ACCESS_TOKEN` with a sidecar that calls `gcloud auth print-access-token`. + + + +For routing rules, rate limits, caching, and the full config reference, see [Agent Command Center → Self-Hosted](/docs/command-center/deployment/self-hosted). + +## PeerDB Replication + +PeerDB continuously replicates Postgres tables into ClickHouse (change-data-capture) so trace and eval analytics stay fast. It runs on its own — the only thing you typically touch is a first-boot timing fix. + + +**First-boot timing.** `peerdb-init` runs the moment the stack starts, sometimes before Django has finished its migrations. If mirrors show "not started" in the PeerDB UI, re-run init once the backend is up: + +```bash +docker compose logs -f backend # wait for "Application startup complete" +docker compose run --rm peerdb-init bash /setup.sh # re-run init +``` + + +Verify at [http://localhost:3001](http://localhost:3001) — mirrors should move to `running` within seconds. Re-run the same init command after any upgrade that changes replicated tables. + +## Temporal Workers + +Temporal runs the platform's background jobs and evaluation pipelines. How those jobs are distributed across workers depends on one flag. + +**All-queue (default).** One worker polls every task queue. Controlled by `TEMPORAL_ALL_QUEUES=true` in `.env`. This is the right setup for most self-hosted deployments. + +**Per-queue (dev overlay).** Six dedicated workers, one per queue, brought up by the [dev overlay](/docs/self-hosting/install#dev-overlay): + +| Service | Queue | Typical concurrency | +|---|---|---| +| `worker-default` | `default` | 100 | +| `worker-tasks-s` | `tasks_s` | 200 | +| `worker-tasks-l` | `tasks_l` | 50 | +| `worker-tasks-xl` | `tasks_xl` | 10 | +| `worker-trace-ingestion` | `trace_ingestion` | 100 | +| `worker-agent-compass` | `agent_compass` | 50 | + +Tune throughput with `TEMPORAL_MAX_CONCURRENT_ACTIVITIES` and `TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASKS` in `.env`. The Temporal UI is available in dev mode at [http://localhost:8085](http://localhost:8085). + +## Dive Deeper + + + + Hardening, backups, and monitoring before going live. + + + Fixes for gateway, PeerDB, and Temporal errors. + + From 90fc401d0b5414e6aaededc221cd66274f5e57cd Mon Sep 17 00:00:00 2001 From: Abhijai Srivastava Date: Wed, 1 Jul 2026 17:22:16 +0530 Subject: [PATCH 2/4] docs: align frontmatter with review standards - title: sentence case to match sidebar label - description: remove em-dash, shorten to single purpose line TH-6329 --- src/pages/docs/self-hosting/configuration/system.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/self-hosting/configuration/system.mdx b/src/pages/docs/self-hosting/configuration/system.mdx index 11be1545..a32cafa5 100644 --- a/src/pages/docs/self-hosting/configuration/system.mdx +++ b/src/pages/docs/self-hosting/configuration/system.mdx @@ -1,6 +1,6 @@ --- -title: "System Configuration" -description: "Configure the moving parts beyond .env — the LLM gateway config.yaml with provider keys, PeerDB Postgres-to-ClickHouse replication mirrors, and Temporal worker concurrency." +title: "System configuration" +description: "Configure the LLM gateway, PeerDB replication, and Temporal workers for your self-hosted instance." --- ## Introduction From d775e2d27e50edbf9d6936eac734c656ee94ddb6 Mon Sep 17 00:00:00 2001 From: Abhijai Srivastava Date: Thu, 2 Jul 2026 22:18:30 +0530 Subject: [PATCH 3/4] docs: address Khushal's review on system configuration - Fix /configure -> /configuration link typo on the overview (prose + card) - Rename System configuration opener from Introduction to In this page - Drop em-dashes across the page (intro + gateway/PeerDB sections) - Fix gateway config path: agentcc-gateway is at repo root, not under futureagi/ --- src/pages/docs/self-hosting.mdx | 4 ++-- .../self-hosting/configuration/system.mdx | 20 +++++++++---------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/src/pages/docs/self-hosting.mdx b/src/pages/docs/self-hosting.mdx index e2dd80c7..28ddd24f 100644 --- a/src/pages/docs/self-hosting.mdx +++ b/src/pages/docs/self-hosting.mdx @@ -36,7 +36,7 @@ postgres ──── PeerDB CDC ──── clickhouse (continuous replicati - **Workflow**: `temporal` - **CDC**: PeerDB (continuous Postgres → ClickHouse replication) -Everything runs on your machines; nothing leaves your network. The full service-by-service breakdown lives in [Configure](/docs/self-hosting/configure) +Everything runs on your machines; nothing leaves your network. The full service-by-service breakdown lives in [Configure](/docs/self-hosting/configuration). ## Deployment options @@ -49,7 +49,7 @@ Everything runs on your machines; nothing leaves your network. The full service- ## Where to go next - + System requirements, prerequisites, environment variables, and setup diff --git a/src/pages/docs/self-hosting/configuration/system.mdx b/src/pages/docs/self-hosting/configuration/system.mdx index a32cafa5..99aba25c 100644 --- a/src/pages/docs/self-hosting/configuration/system.mdx +++ b/src/pages/docs/self-hosting/configuration/system.mdx @@ -3,28 +3,28 @@ title: "System configuration" description: "Configure the LLM gateway, PeerDB replication, and Temporal workers for your self-hosted instance." --- -## Introduction +## In this page -A few parts of the stack are configured outside `.env`: the LLM gateway needs a `config.yaml` listing its providers, PeerDB needs its replication mirrors running, and Temporal workers can be tuned for throughput. This page covers all three. Set your secrets and provider keys in [Environment Variables](/docs/self-hosting/configuration/environment) first — the config here references them. +A few parts of the stack are configured outside `.env`: the LLM gateway needs a `config.yaml` listing its providers, PeerDB needs its replication mirrors running, and Temporal workers can be tuned for throughput. This page covers all three. Set your secrets and provider keys in [Environment Variables](/docs/self-hosting/configuration/environment) first, since the config here references them. ## LLM Gateway The gateway is a Go proxy that routes every model call the platform makes. It reads a `config.yaml` that lists which providers it may use and which models each exposes. -Model calls fail until this file exists. The gateway ships with `config.example.yaml` (OpenAI enabled) but **not** a live `config.yaml` — you create one in the steps below. +Model calls fail until this file exists. The gateway ships with `config.example.yaml` (OpenAI enabled) but **not** a live `config.yaml`. You create one in the steps below. ```bash -cp futureagi/agentcc-gateway/config.example.yaml \ - futureagi/agentcc-gateway/config.yaml +cp agentcc-gateway/config.example.yaml \ + agentcc-gateway/config.yaml ``` -Edit `config.yaml` — uncomment the providers you want and reference their keys with `${VAR}` interpolation. Set the matching keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, …) in `.env`. See the provider examples below. +Edit `config.yaml`: uncomment the providers you want and reference their keys with `${VAR}` interpolation. Set the matching keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, …) in `.env`. See the provider examples below. @@ -32,7 +32,7 @@ Point the gateway volume at your `config.yaml` in `docker-compose.yml`: ```yaml volumes: - - ./futureagi/agentcc-gateway/config.yaml:/app/config.yaml:ro + - ./agentcc-gateway/config.yaml:/app/config.yaml:ro ``` ```bash @@ -42,7 +42,7 @@ docker compose up -d --force-recreate gateway -`config.yaml` is gitignored and holds live API keys. Treat it as a secret — never commit it. +`config.yaml` is gitignored and holds live API keys. Treat it as a secret. Never commit it. ### Provider Examples @@ -99,7 +99,7 @@ For routing rules, rate limits, caching, and the full config reference, see [Age ## PeerDB Replication -PeerDB continuously replicates Postgres tables into ClickHouse (change-data-capture) so trace and eval analytics stay fast. It runs on its own — the only thing you typically touch is a first-boot timing fix. +PeerDB continuously replicates Postgres tables into ClickHouse (change-data-capture) so trace and eval analytics stay fast. It runs on its own. The only thing you typically touch is a first-boot timing fix. **First-boot timing.** `peerdb-init` runs the moment the stack starts, sometimes before Django has finished its migrations. If mirrors show "not started" in the PeerDB UI, re-run init once the backend is up: @@ -110,7 +110,7 @@ docker compose run --rm peerdb-init bash /setup.sh # re-run init ``` -Verify at [http://localhost:3001](http://localhost:3001) — mirrors should move to `running` within seconds. Re-run the same init command after any upgrade that changes replicated tables. +Verify at [http://localhost:3001](http://localhost:3001). Mirrors should move to `running` within seconds. Re-run the same init command after any upgrade that changes replicated tables. ## Temporal Workers From 19305bb8af5205bf805389642000f4089a0aadfd Mon Sep 17 00:00:00 2001 From: khushalsonawat Date: Mon, 6 Jul 2026 12:05:02 +0530 Subject: [PATCH 4/4] docs(self-hosting): point sidebar at nested System configuration; fix stale install link (#695 review) --- src/lib/navigation.ts | 2 +- src/pages/docs/self-hosting/configuration/system.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib/navigation.ts b/src/lib/navigation.ts index db314c4d..47908b1a 100644 --- a/src/lib/navigation.ts +++ b/src/lib/navigation.ts @@ -66,7 +66,7 @@ export const tabNavigation: NavTab[] = [ title: 'Configuration', items: [ { title: 'Environment variables', href: '/docs/self-hosting/environment' }, - { title: 'System configuration', href: '/docs/self-hosting/configuration' }, + { title: 'System configuration', href: '/docs/self-hosting/configuration/system' }, ] }, { diff --git a/src/pages/docs/self-hosting/configuration/system.mdx b/src/pages/docs/self-hosting/configuration/system.mdx index 99aba25c..b28489dc 100644 --- a/src/pages/docs/self-hosting/configuration/system.mdx +++ b/src/pages/docs/self-hosting/configuration/system.mdx @@ -118,7 +118,7 @@ Temporal runs the platform's background jobs and evaluation pipelines. How those **All-queue (default).** One worker polls every task queue. Controlled by `TEMPORAL_ALL_QUEUES=true` in `.env`. This is the right setup for most self-hosted deployments. -**Per-queue (dev overlay).** Six dedicated workers, one per queue, brought up by the [dev overlay](/docs/self-hosting/install#dev-overlay): +**Per-queue (dev overlay).** Six dedicated workers, one per queue, brought up by the [dev overlay](/docs/self-hosting/installation#other-ways-to-run-it): | Service | Queue | Typical concurrency | |---|---|---|