Configuration Reference

When Self-Hosting, 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:

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-<value>`. 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

# Database
DATABASE_URL="postgresql://postgres:postgres@postgres:5432/corgtex"

# Core App
APP_URL="http://localhost:3000"
SESSION_COOKIE_SECRET="<replace-with-32-character-random-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="<replace-with-bootstrap-admin-password>"
CONTROL_PLANE_TESTER_EMAIL="control-plane-qa@acme.com"
CONTROL_PLANE_TESTER_PASSWORD="<replace-with-separate-control-plane-test-password>"

# LLM Config (Optional)
MODEL_PROVIDER="openrouter"
MODEL_API_KEY="<replace-with-provider-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="..."

​Core Application Settings

​Build-Time Production Settings

​Initial Seeding Settings

​Model Provider Settings

​Performance and Session Coordination

​Intercom Support Settings

​Corgtex Connector Settings

​Azure public URL release contract

​Google Workspace Integration

​Object Storage

​Hosted Control Plane Settings

​Example .env File

Core Application Settings

Build-Time Production Settings

Initial Seeding Settings

Model Provider Settings

Performance and Session Coordination

Intercom Support Settings

Corgtex Connector Settings

Azure public URL release contract

Google Workspace Integration

Object Storage

Hosted Control Plane Settings

Example `.env` File