> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corgtex.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration Reference
> Reference for environment variables used to configure a Corgtex deployment.
When [Self-Hosting](/deploy/docker-compose), you configure Corgtex using environment variables (typically stored in a `.env` file).
## Core Application Settings
The variables defined here are strictly required to start the web and worker processes successfully.
| Variable | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | The PostgreSQL connection string. Must include credentials and the database name. Example: `postgresql://postgres:pass@localhost:5432/corgtex` |
| `APP_URL` | The fully qualified base URL where this runtime is hosted (for example, `https://app.corgtex.com` for the dogfood product app, `https://ops.corgtex.com` for Ops, or a customer runtime domain). Used for OAuth redirects and webhook signing. |
| `SESSION_COOKIE_SECRET` | A 32+ character random string used for signing secure cookies. Never expose this. |
## Build-Time Production Settings
Production web image builds also require stable build metadata. These values are consumed while building the Next.js app and must be supplied by the build system without committing secrets.
| Variable | Description |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` | Build-time-only 32-byte base64 key used by Next.js Server Actions that still remain in the app. Required for production web image builds so every instance of the same release can decrypt and identify Server Actions consistently. Generate once per environment and provide it as a Docker BuildKit secret or equivalent build secret; do not commit it or print it in logs. |
| `CORGTEX_RELEASE_GIT_SHA` | Preferred immutable release SHA used for the Next.js `deploymentId`, build ID, and `/api/health` release metadata. The release workflow sets this from the Git commit SHA. |
| `RAILWAY_GIT_COMMIT_SHA` / `GITHUB_SHA` | Fallback SHA sources used when `CORGTEX_RELEASE_GIT_SHA` is absent. |
## Initial Seeding Settings
When you launch a fresh Corgtex instance, the database must be seeded with an initial workspace and an administrative user.
| Variable | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `WORKSPACE_NAME` | The display name of the initial workspace (e.g., "Acme Corp"). |
| `WORKSPACE_SLUG` | The URL-friendly identifier for the workspace (e.g., "acme-corp"). |
| `ADMIN_EMAIL` | The email address for the initial bootstrap admin user. |
| `ADMIN_PASSWORD` | The password for the initial bootstrap admin user. |
| `CONTROL_PLANE_TESTER_EMAIL` | Optional separate global operator email for auditable Control Plane production testing. Must differ from `ADMIN_EMAIL`. |
| `CONTROL_PLANE_TESTER_PASSWORD` | Password for the optional Control Plane tester account. Required when `CONTROL_PLANE_TESTER_EMAIL` creates the account, or when `SEED_RESET_PASSWORDS=true`. |
| `CONTROL_PLANE_TESTER_DISPLAY_NAME` | Optional display name for the Control Plane tester account. Defaults to "Control Plane Test Operator". |
| `SEED_SCRIPTS` | Optional comma-separated list of extra Node seed scripts to run after the base seed at web startup. Use only for public-safe or deployment-specific fixtures. |
| `CORGTEX_AUTO_SEED_JNJ_DEMO` | Set to `true` only on shared demo/trial runtimes that should refresh the public J\&J demo workspace on each deploy. This runs `scripts/seed-jnj-demo.mjs` after the base seed. |
## Model Provider Settings
By default, the platform relies on external Large Language Models to power the Organization Brain and agents. While these are optional at startup, they are recommended for full functionality.
| Variable | Description |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MODEL_PROVIDER` | Defines which LLM gateway to use. Valid options: `openrouter`, `openai`, `azure-openai`, `azure-foundry`. |
| `MODEL_API_KEY` | Your API key for OpenAI-compatible non-Azure providers. |
| `MODEL_BASE_URL` | OpenAI-compatible v1 base URL. For Azure Foundry keyless auth, use the Azure AI Services `/openai/v1` endpoint. |
| `MODEL_PROVIDER_ROUTES_JSON` | Optional exact model-to-provider route map for canaries and rollback routes. |
| `AZURE_OPENAI_AUTH_MODE` | `api_key` or `managed_identity` for Azure OpenAI-compatible providers. |
| `AZURE_OPENAI_API_KEY` | Azure API key when API key authentication is approved. |
| `MODEL_CHAT_DEFAULT` | The specific model string to use for conversational features (e.g., `google/gemma-4-31b-it`). |
| `MODEL_EMBEDDING_DEFAULT` | The specific model string to use for vector embeddings (e.g., `text-embedding-3-small`). |
| `MODEL_PRICE_OVERRIDES_JSON` | Required for Azure deployments without built-in pricing. |
| `MODEL_OMIT_TEMPERATURE_MODELS` | Optional comma-separated deployment aliases whose provider rejects `temperature`; `corgtex-gpt56-luna` is always treated this way. |
| `KNOWLEDGE_SEARCH_PROVIDER` | Retrieval backend for indexed Brain chunks. Defaults to `postgres`; set to `azure` or `dual_compare` after Azure Search is configured and backfilled. |
| `AZURE_SEARCH_ENDPOINT` | Azure AI Search service endpoint, for example `https://example.search.windows.net`. Required for Azure retrieval. |
| `AZURE_SEARCH_INDEX_NAME` | Per-deployment Azure Search index name for Corgtex knowledge chunks. |
| `AZURE_SEARCH_AUTH_MODE` | `api_key` for Railway or `managed_identity` for Azure-hosted runtimes. Defaults to `api_key`. |
| `AZURE_SEARCH_ADMIN_KEY` | Server-side key used by workers/backfill jobs to write Azure Search documents. |
| `AZURE_SEARCH_QUERY_KEY` | Server-side key used by web/API processes to query Azure Search. Falls back to admin key if omitted. |
| `AZURE_SEARCH_API_VERSION` | Azure Search REST API version. Defaults to `2026-04-01`. |
| `AZURE_SEARCH_VECTOR_DIMENSIONS` | Embedding dimensions for the Azure Search vector field. Defaults to `1536`. |
Setting `MODEL_PROVIDER` allows Corgtex's internal abstractions to handle the LLM routing without baking a specific vendor dependency into your infrastructure.
## Performance and Session Coordination
Production and client instances should use Redis for shared short-lived state. Postgres remains the permanent source of truth.
| Variable | Description |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `REDIS_URL` | Redis connection string used for shared rate limiting, short-lived Brain retrieval cache, and session heartbeat throttling. Required for scaled production/client deployments. |
| `REDIS_KEY_PREFIX` | Prefix for Redis keys. Use a deployment-specific value such as `corgtex-prod` or `crina-prod` so environments do not collide. |
| `SESSION_LAST_SEEN_WRITE_INTERVAL_MS` | Optional session heartbeat throttle. Defaults to `300000` (5 minutes). |
On Railway, add a Redis service in the same project and environment as the app, then set `REDIS_URL` on every runtime service that handles requests or jobs, normally web and worker. Use Railway reference variables, for example:
```env theme={null}
REDIS_URL="${{Redis.REDIS_URL}}"
REDIS_KEY_PREFIX="client-slug-prod"
```
## Intercom Support Settings
These variables enable Intercom Messenger and Fin support on hosted Corgtex site/app surfaces. Leave them unset for customer-owned or self-managed runtimes unless that customer explicitly wants Intercom enabled.
| Variable | Description |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_INTERCOM_APP_ID` | Intercom Messenger app ID for the shared Corgtex support workspace. This is safe to expose to the browser. |
| `NEXT_PUBLIC_INTERCOM_API_BASE` | Messenger API base for the Intercom workspace region. Defaults to `https://api-iam.intercom.io`. |
| `INTERCOM_MESSENGER_SECRET` | Server-only Messenger JWT secret from Intercom's Messenger Security settings. Required for authenticated app users and must never be exposed to browser code, logs, PRs, or support messages. |
## Corgtex Connector Settings
These variables configure the remote MCP connector used by ChatGPT, Claude, Cursor, and other MCP clients.
| Variable | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MCP_PUBLIC_URL` | Public connector URL shown in the UI and used as the OAuth resource audience. Defaults to `${APP_URL}/mcp`. For the central connector, use a stable URL such as `https://mcp.corgtex.com/mcp`. |
| `MCP_DEFAULT_INSTANCE_SLUG` | Optional instance slug for this deployment. If omitted, Corgtex uses `WORKSPACE_SLUG` or infers `crina` from a Crina host name. |
| `MCP_INSTANCE_REGISTRY` | Optional JSON array of registered connector instances. Each entry supports `slug`, `displayName`, `baseUrl`, `workspaceIds`, `workspaceSlugs`, and `status`. Unknown workspaces are rejected when a registry is configured. |
### Azure public URL release contract
Fleet releases derive a canonical origin from each Azure target URL. Before any ACR import or Container App update, both the web and worker apps must expose `APP_URL`, `NEXT_PUBLIC_APP_URL`, and `MEETING_RECORDER_PUBLIC_BASE_URL` as that exact origin and `MCP_PUBLIC_URL` as `${origin}/mcp`. Missing values, secret references, origin-only MCP URLs, and URLs for another customer block the release instead of being normalized.
After the Azure update, the release runner repeats the runtime check and verifies the public OAuth protected-resource metadata, authorization-server issuer and endpoints, default scopes, and unauthenticated challenges on `/mcp` and `/api/mcp`. A mismatch blocks verified-release recording.
## Google Workspace Integration
These variables enable Google Calendar sync and selected-file Google Drive ingestion.
| Variable | Description |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GOOGLE_CLIENT_ID` | OAuth web client ID from Google Auth Platform. Register `${APP_URL}/api/integrations/google/callback` as an authorized redirect URI and `${APP_URL}` as an authorized JavaScript origin. |
| `GOOGLE_CLIENT_SECRET` | OAuth web client secret. Store only as a server-side deployment secret. |
| `NEXT_PUBLIC_GOOGLE_PICKER_API_KEY` | Browser-safe Google Picker API key, restricted in Google Cloud to the production app origin such as `https://app.corgtex.com`. |
| `NEXT_PUBLIC_GOOGLE_CLOUD_PROJECT_NUMBER` | Google Cloud project number used as the Picker app ID. This is not a secret. |
Corgtex requests `https://www.googleapis.com/auth/calendar.readonly` for calendar sync and `https://www.googleapis.com/auth/drive.file` for selected Drive files. Do not add broad Drive scopes unless a separate product requirement and Google verification justification are approved.
## Object Storage
File uploads and Brain source downloads use an S3-compatible storage backend. Client instances that allow uploads must configure this for every runtime service that touches uploads, normally web and worker.
| Variable | Description |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| `S3_ENDPOINT` | S3-compatible endpoint. For Railway buckets this is the bucket credential endpoint. |
| `S3_BUCKET_NAME` | Bucket name used by the app. |
| `AWS_S3_BUCKET_NAME` | Compatibility alias for bucket name. Set to the same value as `S3_BUCKET_NAME`. |
| `S3_REGION` | Storage region. Railway buckets commonly use `auto`. |
| `S3_ACCESS_KEY_ID` | S3-compatible access key ID. |
| `S3_SECRET_ACCESS_KEY` | S3-compatible secret access key. |
| `S3_ACCESS_KEY` | Compatibility alias for access key ID. Set to the same value as `S3_ACCESS_KEY_ID`. |
| `S3_SECRET_KEY` | Compatibility alias for secret access key. Set to the same value as `S3_SECRET_ACCESS_KEY`. |
On Railway, create or reuse a project bucket, read its S3-compatible credentials with the Railway dashboard or CLI, and set the variables above on web and worker. Do not print access keys or secret keys in logs, PRs, tickets, or support messages.
## Hosted Control Plane Settings
These variables are only needed by the dedicated Corgtex Ops control plane or by product/customer runtimes that need to link back to it. The canonical public Ops host is `https://ops.corgtex.com`; raw Railway service URLs are implementation URLs only.
| Variable | Description |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `RAILWAY_API_TOKEN` | Railway API token used by the internal control plane to provision customer projects and services. Store only as a deployment secret. |
| `RAILWAY_GRAPHQL_ENDPOINT` | Optional override for Railway's GraphQL endpoint. Leave unset unless Railway support directs otherwise. |
| `CONTROL_PLANE_MODE` | Set to `true` only for the dedicated Ops deployment. Operators landing on `/` are sent to `/control-plane`, and control-plane UI/API routes are active only in this mode. |
| `CONTROL_PLANE_URL` | Canonical Ops origin used by non-Ops deployments when linking or redirecting to the control plane. Production product and customer runtimes should set this to `https://ops.corgtex.com`. Local development can leave it unset to keep links relative. |
| `CONTROL_PLANE_AGENT_API_KEY` | Bearer secret for control-plane CLI/MCP automation. Requests use `Authorization: Bearer cp-`. Store only as a deployment secret. |
| `CONTROL_PLANE_AGENT_SCOPES` | Optional comma- or space-separated scopes for control-plane CLI/MCP automation. Omit for read-only access; include only the mutation scopes needed by the operator workflow. |
| `CORGTEX_CUSTOMER_DEPLOYMENT_BOOTSTRAP_TOKEN_HASH` | SHA-256 hash of the one-time bearer token accepted by a customer runtime's internal bootstrap endpoint. Prefer this over storing the raw token. |
| `CORGTEX_CUSTOMER_DEPLOYMENT_BOOTSTRAP_TOKEN` | Legacy raw-token fallback for bootstrap endpoints. Use only while rotating to `CORGTEX_CUSTOMER_DEPLOYMENT_BOOTSTRAP_TOKEN_HASH`. |
| `CORGTEX_RELEASE_VERSION` | Release version reported by `/api/health` for fleet drift checks. |
| `CORGTEX_RELEASE_IMAGE_TAG` | Immutable image tag reported by `/api/health` and used by the control plane for customer deployments. |
The dedicated Ops control plane exposes operator-only routes for automation. These routes return unavailable outside `CONTROL_PLANE_MODE=true`, even if the code is deployed on `app.corgtex.com` or a customer runtime:
| Route | Purpose |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `GET /api/admin/customer-deployments` | List managed customer deployments and their operational status. |
| `POST /api/admin/customer-deployments` | Provision a dedicated customer project from pinned release images and private bundle metadata. |
| `POST /api/admin/customer-deployments/:deploymentId/health` | Probe the customer runtime health endpoint and record release drift. |
| `POST /api/admin/customer-deployments/:deploymentId/bootstrap` | Trigger one-time private bundle bootstrap on the customer runtime. |
| `POST /api/admin/customer-deployments/:deploymentId/upgrade` | Update pinned release images and redeploy web and worker services. |
| `POST /api/admin/customer-deployments/:deploymentId/suspend` | Mark a customer deployment suspended in the control plane. |
| `GET /api/control-plane/deployments` | List customer deployments for operator dashboards or automation. |
| `POST /api/control-plane/deployments/:deploymentId/support-connector` | Store or rotate an encrypted support connector credential for a customer deployment. |
| `POST /api/control-plane/deployments/:deploymentId/snapshot` | Pull a live support snapshot through the customer support connector. |
| `POST /api/control-plane/deployments/:deploymentId/operations` | Run an audited support operation through the support connector. |
| `POST /api/control-plane/mcp` | MCP-style control-plane automation endpoint for agents and CLI support workflows. |
Old UI links under `/control-plane/customers/:deploymentId` are kept as compatibility redirects only. New operator links must use `/control-plane/deployments/:deploymentId`.
## Example `.env` File
```env theme={null}
# Database
DATABASE_URL="postgresql://postgres:postgres@postgres:5432/corgtex"
# Core App
APP_URL="http://localhost:3000"
SESSION_COOKIE_SECRET=""
NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=""
# Seed Data (First Workspace)
WORKSPACE_NAME="Acme Demo"
WORKSPACE_SLUG="acme-demo"
ADMIN_EMAIL="admin@acme.com"
ADMIN_PASSWORD=""
CONTROL_PLANE_TESTER_EMAIL="control-plane-qa@acme.com"
CONTROL_PLANE_TESTER_PASSWORD=""
# LLM Config (Optional)
MODEL_PROVIDER="openrouter"
MODEL_API_KEY=""
MODEL_CHAT_DEFAULT="anthropic/claude-3.5-sonnet"
MODEL_EMBEDDING_DEFAULT="openai/text-embedding-3-small"
# Redis (Production / Client Instances)
REDIS_URL="redis://redis:6379"
REDIS_KEY_PREFIX="corgtex-local"
# Google Workspace OAuth and Picker
GOOGLE_CLIENT_ID="..."
GOOGLE_CLIENT_SECRET="..."
NEXT_PUBLIC_GOOGLE_PICKER_API_KEY="..."
NEXT_PUBLIC_GOOGLE_CLOUD_PROJECT_NUMBER="..."
# S3-Compatible Storage
S3_ENDPOINT="https://storage.example.com"
S3_BUCKET_NAME="corgtex"
AWS_S3_BUCKET_NAME="corgtex"
S3_REGION="auto"
S3_ACCESS_KEY_ID="..."
S3_SECRET_ACCESS_KEY="..."
S3_ACCESS_KEY="..."
S3_SECRET_KEY="..."
```