Configuration

Configuration

Set up Docker Compose, environment variables, and connector secrets for self-hosted ctxpipe.

Environment variables control the configuration. Set only the values that your deployment needs. Treat the required auth, database, model, and public-origin values as production secrets.

What a deployment needs

  • A deployment path: Docker Compose, AWS CDK, or the Terraform stack for Railway and Neon.
  • PostgreSQL with pgvector. Compose and Terraform use PostgreSQL 17. AWS CDK uses Aurora PostgreSQL 16.
  • A graph database. FalkorDB is in the Compose stack.
  • A model provider: OpenRouter, Azure OpenAI, Amazon Bedrock, or another OpenAI-compatible API.
  • A public HTTPS origin for auth callbacks, webhooks, MCP, and Forge.
  • Optional: an SMTP provider for email.

On Docker Compose, set the values in .env. Compose passes only some of them to the services. See Settings that need an override file.

Required variables

The backend does not start without these:

VariableDescription
DATABASE_URLRuntime PostgreSQL URL for backend, worker, and codesearch. Use the ctxpipe_app role, which has no BYPASSRLS. Example: postgresql://ctxpipe_app:pass@host:5432/db. migrate uses the table-owner URL. Compose and AWS CDK set both URLs.
AUTH_SECRETA random string of 32 or more characters, for session signing. Generate it with openssl rand -hex 32. Keep it stable. A new value signs everybody out and, without CONNECTION_SECRETS_ENCRYPTION_KEY, makes the stored connector secrets unreadable.

Set these too for a deployment that people use:

VariableDescription
AUTH_BASE_URLThe public URL of your deployment, for example https://ctx.example.com. The default, https://localhost:3000, works only on your machine.
CTXPIPE_PUBLIC_APP_URLThe public backend URL in the UI image, at build time. Usually the same as AUTH_BASE_URL. Compose and AWS CDK read it.
MODEL_PROVIDER_API_KEYThe API key of your model provider. Required for each provider except bedrock.
CODESEARCH_URLThe URL of codesearch. Repository search and indexing need it. The backend and the worker must both reach it. Compose and AWS CDK set it.

Email

Email is optional. Without both values, ctxpipe turns off email verification and sends no password reset or invitation email. The backend logs a warning.

VariableDescription
SMTP_CONNECTION_URLSMTP connection URL, for example smtps://user:[email protected]:465
EMAIL_FROM_ADDRESSFrom address for transactional email, for example [email protected]
EMAIL_TRANSPORTsmtp (the default) or ses. With ses, the backend sends through the Amazon SES v2 API. It uses the AWS credentials of its process (for example an ECS task role) and its AWS_REGION. It needs no SMTP_CONNECTION_URL. The role needs ses:SendEmail on the sender identity.

Social sign-in

All social providers are optional. Omit the variables to disable that provider.

VariableDescription
GITHUB_CLIENT_IDGitHub OAuth app client ID
GITHUB_CLIENT_SECRETGitHub OAuth app client secret
GOOGLE_CLIENT_IDGoogle OAuth client ID
GOOGLE_CLIENT_SECRETGoogle OAuth client secret
MICROSOFT_CLIENT_IDMicrosoft Entra application client ID
MICROSOFT_CLIENT_SECRETMicrosoft Entra client secret

See Authentication for OAuth and session behavior.

Models and embeddings

VariableDescription
MODEL_PROVIDEROptional. openai-like default, openrouter, azure, or bedrock.
MODEL_PROVIDER_API_KEYAPI key for OpenAI-compatible providers. Omit for native Bedrock IAM.
MODEL_PROVIDER_URLOptional for openai-like and openrouter; required for Azure; not used by native Bedrock.
MODEL_BEDROCK_AWS_REGIONOptional explicit region for native Bedrock; otherwise use the AWS runtime region.
MODEL_FAST_NAME, MODEL_MEDIUM_NAME, MODEL_HIGH_NAMEOptional model names per tier.
MODEL_EMBEDDING_NAMEOptional embedding model ID.

See Model configuration for provider-specific examples and embedding requirements.

Graph database

VariableDescription
GRAPH_DB_PROVIDEROptional. falkordb (default), neo4j-enterprise, neo4j-community, memgraph, or neptune.
GRAPH_DB_URIFalkorDB Redis URI or Bolt URI for another supported graph database.
GRAPH_DB_USER, GRAPH_DB_PASSWORDOptional credentials for providers that require them.

See Graph databases for provider support and tenancy behavior.

Chat sandboxes

Workspace chat runs each conversation's agent in a sandbox. Docker Compose and AWS CDK set these values for you. On other platforms, set them on the backend and the worker.

VariableDescription
SANDBOX_PROVIDERdocker, vercel, agentcore, or unsandboxed. Set it to docker on a self-hosted deployment; Docker Compose and AWS CDK set it. Without a value, chat uses Docker, but the plain git rules then use the strict hosted rule: they use the self-host rule only when the value is exactly docker (see below). If the Docker daemon does not answer, chat returns 503. The backend and worker images refuse unsandboxed: it is only for local development.
DOCKER_HOSTDocker API address, for example tcp://dind:2376. If you do not set it, the backend uses the local Docker socket.
DOCKER_TLS_VERIFY, DOCKER_CERT_PATHMutual TLS to the Docker API. Set DOCKER_TLS_VERIFY=1. DOCKER_CERT_PATH is a directory with ca.pem, cert.pem, and key.pem.
SANDBOX_CHAT_IMAGEChat sandbox image on that daemon. The default is ctxpipe-chat-sandbox:opencode-<version>, which is in no registry. On other platforms, build scripts/chat-sandbox on that daemon, or use ghcr.io/ctxpipe-ai/chat-sandbox:<backend commit SHA> once that package is public. Compose builds ctxpipe-chat-sandbox:local. AWS CDK uses ghcr.io/ctxpipe-ai/chat-sandbox at the commit SHA tag that the package pins.
SANDBOX_CALLBACK_HOSTOptional. Host name that sandboxes use to send requests to the backend, through Agent Vault. It must be a host name with a dot (for example backend.sandbox.ctxpipe.internal), not an IP address: Agent Vault rules take host names. If you do not set it and DOCKER_HOST is remote, the backend uses its own address on the route to the Docker daemon, which works only with SANDBOX_CALLBACK_DNS_SUFFIX. Compose sets it.
SANDBOX_CALLBACK_DNS_SUFFIXOptional. With it, that derived address becomes the name ip-<a>-<b>-<c>-<d>.<suffix>, for example the VPC DNS name on AWS. AWS CDK sets it.
AGENT_VAULT_ADDRRequired for Docker sandboxes. The Agent Vault API, for example http://agent-vault:14321. Without it, or when Agent Vault does not answer, Docker chat returns 503. Compose and AWS CDK set it.
AGENT_VAULT_OWNER_PASSWORD, AGENT_VAULT_OWNER_PASSWORD_FILEThe Agent Vault owner password, as a value or as a file. Compose and AWS CDK generate it; do not set it there. On other platforms, generate one and keep it: the backend registers it on its first login, and an Agent Vault with an owner refuses another password.
VERCEL_TOKEN, VERCEL_TEAM_ID, VERCEL_PROJECT_IDRequired when SANDBOX_PROVIDER=vercel. A Vercel access token, and the team and project (slug or id) that own the sandboxes. Hosted ctxpipe uses this provider.
AGENTCORE_RUNTIME_ARN, AGENTCORE_RUNTIME_QUALIFIERRequired when SANDBOX_PROVIDER=agentcore (hosted ctxpipe on AWS; AWS CDK does not support it yet). The ARN of the Amazon Bedrock AgentCore runtime that runs the agentcore target of the chat sandbox image, and its endpoint name (default DEFAULT). The backend also needs Agent Vault, and SANDBOX_CALLBACK_DNS_SUFFIX or SANDBOX_CALLBACK_HOST. Each process in the sandbox can read the credentials of the runtime's execution role at 169.254.169.254. Thus that role must allow only the pull from the sandbox image's repository. It must also allow log group creation and log writes, only on the runtime's own log group. It must refuse each request that does not come through the sandbox VPC endpoints. AgentCore's own BedrockAgentCore-* sessions are the exception: AgentCore creates the log group from its own network. The ingest check allows that address because of this rule.

Plain git repositories

A plain git repository is a repository that ctxpipe reads with no credential (see Linked repositories). With SANDBOX_PROVIDER=docker, its URL can use https:// or http://, another port, an IP address, or an internal host name. ssh (git@… or ssh://), git://, and file:// URLs are not supported. ctxpipe never reads a host that resolves to a cloud metadata or link-local address (169.254.0.0/16, fe80::/10, or fd00:ec2::254). With each other value of SANDBOX_PROVIDER, or with no value, the URL must use https:// on the default port, and each address of its host must be public. The backend and codesearch read the repository through the proxy of their environment (HTTPS_PROXY, NO_PROXY), if you set one.

VariableDescription
AGENT_VAULT_NETWORK_ALLOWLISTDocker Compose only (.env). Optional. The private addresses and CIDRs that Agent Vault may connect to, separated by commas. Compose always allows 172.30.99.10, the backend, and adds your entries after it. To ingest a plain git repository on a private git server, add only the single host address of your git server, for example 10.20.0.15. Without it, the ingestion sandbox cannot fetch the repository. Chat-sandbox vaults forward each host that no rule matches. An address or CIDR in this list therefore lets every chat agent reach every port and path at that address. Add only the single host address of the git server, never a whole subnet. Never add a range that covers 172.30.99.0/24, and never add a link-local (169.254.0.0/16), loopback, or cloud metadata range. On AWS CDK, use sandboxHost.agentVaultNetworkAllowlist (see AWS).

GitHub App connector

Repository connectors use a GitHub App that your deployment owns. The in-product wizard stores the ID, the PEM private key, and the webhook secret of the App, encrypted, for the connection.

VariableDescription
GITHUB_APP_IDOptional after migrations. GitHub App numeric ID.
GITHUB_PRIVATE_KEYOptional after migrations. PEM private key for the App.
GITHUB_WEBHOOK_SECRETOptional after migrations. Also used for the legacy webhook route.
GITHUB_APP_SLUGOptional. Public app slug used for default install URLs.
CONNECTION_SECRETS_ENCRYPTION_KEYOptional 64-character hex key. When unset, encryption derives from AUTH_SECRET.

The wizard reserves the connection-specific webhook URL and gives the exact value to paste into GitHub.

OAuth sign-in is separate

GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are for signing in with GitHub. GitHub App credentials are for repository installation and webhook access.

See GitHub for App registration, permissions, events, credentials, installation, and end-to-end verification.

Atlassian and Confluence

Self-hosted Confluence uses the same product wizard as hosted ctxpipe. But your deployment or organization must first provide the Atlassian and Forge settings.

VariableDescription
ATLASSIAN_CLIENT_ID, ATLASSIAN_CLIENT_SECRETOptional global Atlassian 3LO app for account linking. If unset, each Forge connection can store its own 3LO credentials through the wizard.
CONFLUENCE_FORGE_INSTALL_URLOptional deployment-wide Forge install URL fallback when a Forge connection has no install URL in connections.config.

See Confluence & Atlassian for the full operator flow.

Slack

Self-hosted Slack uses one Slack app that your deployment owns. Organizations authorize that app. They do not create per-tenant Slack apps or Event Subscription URLs.

VariableDescription
SLACK_CLIENT_ID, SLACK_CLIENT_SECRETSlack app OAuth credentials. Required to enable the Slack connector.
SLACK_SIGNING_SECRETVerifies Event Subscription requests (X-Slack-Signature).
SLACK_REDIRECT_URIOptional. Override when the public OAuth callback differs from {AUTH_BASE_URL}/api/v1/connectors/slack/oauth/callback.

Set the client ID, client secret, and signing secret together. Then restart or redeploy the backend. The backend and the worker must share the same AUTH_SECRET and, when configured, CONNECTION_SECRETS_ENCRYPTION_KEY. Then the background capture jobs can use the encrypted Slack bot tokens.

Set the Slack Event Subscriptions Request URL to:

https://<public-origin>/api/v1/webhook/slack

See Slack for scopes, app_mention Events, and intent-based thread capture.

Linear

ctxpipe can store the Linear OAuth application and the webhook signing secret on the connection (Register in the product UI). LINEAR_* is an optional deployment-wide fallback.

VariableDescription
LINEAR_CLIENT_ID, LINEAR_CLIENT_SECRETOptional shared Linear OAuth application credentials. When both are set, the wizard skips Register.
LINEAR_REDIRECT_URIOptional exact callback override. Defaults to {AUTH_BASE_URL}/api/v1/integrations/linear/callback.
LINEAR_WEBHOOK_SECRETOptional shared signing secret for /api/v1/webhook/linear. Per-connection secrets are stored on the row.

See Linear for application registration, webhook subscriptions, preview limitations, and troubleshooting.

Notion

Notion uses one public integration and one webhook subscription. Your deployment owns both.

VariableDescription
NOTION_CLIENT_ID, NOTION_CLIENT_SECRETPublic integration OAuth credentials. Both are required to enable the connector.
NOTION_REDIRECT_URIOptional exact callback override. Defaults to {AUTH_BASE_URL}/api/v1/connectors/notion/oauth/callback.
NOTION_WEBHOOK_SECRETVerification token shown by Notion after the first webhook delivery. Required for signed updates.

Put the OAuth credentials on every service that refreshes tokens or does connector work. Then register the single deployment webhook. See Notion for provisioning and verification.

PagerDuty

PagerDuty can use an OAuth application that your deployment owns. After a user authorizes an account, ctxpipe creates the signed webhook subscription. These variables are an optional shortcut, as on hosted ctxpipe. A self-hosted deployment can instead save the app on the connection in the setup wizard.

VariableDescription
PAGERDUTY_CLIENT_ID, PAGERDUTY_CLIENT_SECRETOptional shared PagerDuty OAuth application. When unset, save client id and secret on the connection in the wizard.
PAGERDUTY_REDIRECT_URIOptional exact callback override. Defaults to {AUTH_BASE_URL}/api/v1/integrations/pagerduty/callback.

There is no PAGERDUTY_WEBHOOK_SECRET. ctxpipe stores the signing secret of each subscription encrypted on the connection.

See PagerDuty for application registration and verification.

Observability

Telemetry is off until you set it. ctxpipe does not ship a collector, Langfuse, or ClickStack in the Compose deploy profile or in @ctxpipe/aws-cdk. Unset values keep logs on stdout and do not start trace or metric export. Empty values count as unset.

Point the signal URLs at your own OTLP/HTTP backend. Export starts from these variables. Include the signal path on each URL.

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otel.example.com/v1/traces
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://otel.example.com/v1/logs
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://otel.example.com/v1/metrics
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer xxx
VariableDescription
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTTraces URL, including /v1/traces. Trace export stays off when this is unset.
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTLogs URL, including /v1/logs. Unset keeps logs on stdout.
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTMetrics URL, including /v1/metrics.
OTEL_EXPORTER_OTLP_HEADERSOptional headers, for example Authorization=Bearer xxx.
OTEL_SERVICE_NAMEResource service.name. Compose and CDK set backend, openworkflow, ui, and codesearch per container. Compose does not apply a shared name from the root .env.
OTEL_RESOURCE_ATTRIBUTESExtra resource attributes, for example deployment.environment=production.

The deployment.environment value applies to backend traces, metrics, and logs, to the Langfuse environment tag, to codesearch, and to the UI relay. It is DEPLOYMENT_ENVIRONMENT when that is set. Hosted ctxpipe sets this variable; a self-hosted install leaves it unset, because a pr-N value turns on preview behavior (no email verification). Otherwise it is deployment.environment from OTEL_RESOURCE_ATTRIBUTES. Otherwise it is production when NODE_ENV=production. Otherwise it is development. Backend and codesearch also set service.namespace=ctxpipe. Codesearch always exports service.name codesearch.

LLM spans are OpenTelemetry spans. The apps do not read LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, or LANGFUSE_HOST. A Langfuse project accepts traces at https://<your-langfuse>/api/public/otel/v1/traces with Authorization=Basic <base64(publicKey:secretKey)> in OTEL_EXPORTER_OTLP_HEADERS. @ctxpipe/aws-cdk takes one base otel.endpoint and appends /v1/traces, /v1/logs, and /v1/metrics. See AWS.

Browser telemetry

The UI enables browser telemetry only when OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is set on the UI server. The browser posts traces to the same origin at /.otel/v1/traces. The relay also accepts /.otel/v1/logs, but the SDK does not use it. Replay is off, and the SDK emits console capture as spans. The UI server forwards traces to OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and logs to OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, using OTEL_EXPORTER_OTLP_HEADERS. When the traces endpoint is unset, the browser SDK does not start. A signal whose endpoint is unset returns 204.

Advanced

VariableDescription
AUTH_ISSUEROverride the OAuth issuer claim. Defaults to AUTH_BASE_URL.
AUTH_ALLOWED_ORIGINSComma-separated list of allowed CORS origins for auth endpoints.
OPENWORKFLOW_CONCURRENCYIn-flight OpenWorkflow runs per worker process. Default 4 when unset. Compose sets 6. AWS CDK and Terraform set a value for each size.
AUTH_TOKEN_AUDIENCE_CODESEARCHOptional. The audience of the tokens that the backend sends to codesearch. If you set it, set the same value on the backend, the worker, and codesearch.
CODESEARCH_INDEXER_CONCURRENCYMax concurrent Zoekt/SCIP child processes on codesearch, and SCIP HTTP batch size on the worker. Default 2.
CODESEARCH_INDEX_PIPELINE_CONCURRENCYMax distinct repos with in-flight OpenWorkflow index-phase HTTP (clone included). Default 2. Codesearch returns 429 when full.

Railway

To run ctxpipe on Railway with the prebuilt images, start from the Terraform stack.