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:
| Variable | Description |
|---|---|
DATABASE_URL | Runtime 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_SECRET | A 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:
| Variable | Description |
|---|---|
AUTH_BASE_URL | The public URL of your deployment, for example https://ctx.example.com. The default, https://localhost:3000, works only on your machine. |
CTXPIPE_PUBLIC_APP_URL | The 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_KEY | The API key of your model provider. Required for each provider except bedrock. |
CODESEARCH_URL | The 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 is optional. Without both values, ctxpipe turns off email verification and sends no password reset or invitation email. The backend logs a warning.
| Variable | Description |
|---|---|
SMTP_CONNECTION_URL | SMTP connection URL, for example smtps://user:[email protected]:465 |
EMAIL_FROM_ADDRESS | From address for transactional email, for example [email protected] |
EMAIL_TRANSPORT | smtp (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.
| Variable | Description |
|---|---|
GITHUB_CLIENT_ID | GitHub OAuth app client ID |
GITHUB_CLIENT_SECRET | GitHub OAuth app client secret |
GOOGLE_CLIENT_ID | Google OAuth client ID |
GOOGLE_CLIENT_SECRET | Google OAuth client secret |
MICROSOFT_CLIENT_ID | Microsoft Entra application client ID |
MICROSOFT_CLIENT_SECRET | Microsoft Entra client secret |
See Authentication for OAuth and session behavior.
Models and embeddings
| Variable | Description |
|---|---|
MODEL_PROVIDER | Optional. openai-like default, openrouter, azure, or bedrock. |
MODEL_PROVIDER_API_KEY | API key for OpenAI-compatible providers. Omit for native Bedrock IAM. |
MODEL_PROVIDER_URL | Optional for openai-like and openrouter; required for Azure; not used by native Bedrock. |
MODEL_BEDROCK_AWS_REGION | Optional explicit region for native Bedrock; otherwise use the AWS runtime region. |
MODEL_FAST_NAME, MODEL_MEDIUM_NAME, MODEL_HIGH_NAME | Optional model names per tier. |
MODEL_EMBEDDING_NAME | Optional embedding model ID. |
See Model configuration for provider-specific examples and embedding requirements.
Graph database
| Variable | Description |
|---|---|
GRAPH_DB_PROVIDER | Optional. falkordb (default), neo4j-enterprise, neo4j-community, memgraph, or neptune. |
GRAPH_DB_URI | FalkorDB Redis URI or Bolt URI for another supported graph database. |
GRAPH_DB_USER, GRAPH_DB_PASSWORD | Optional 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.
| Variable | Description |
|---|---|
SANDBOX_PROVIDER | docker, 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_HOST | Docker 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_PATH | Mutual 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_IMAGE | Chat 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_HOST | Optional. 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_SUFFIX | Optional. 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_ADDR | Required 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_FILE | The 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_ID | Required 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_QUALIFIER | Required 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.
| Variable | Description |
|---|---|
AGENT_VAULT_NETWORK_ALLOWLIST | Docker 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.
| Variable | Description |
|---|---|
GITHUB_APP_ID | Optional after migrations. GitHub App numeric ID. |
GITHUB_PRIVATE_KEY | Optional after migrations. PEM private key for the App. |
GITHUB_WEBHOOK_SECRET | Optional after migrations. Also used for the legacy webhook route. |
GITHUB_APP_SLUG | Optional. Public app slug used for default install URLs. |
CONNECTION_SECRETS_ENCRYPTION_KEY | Optional 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.
| Variable | Description |
|---|---|
ATLASSIAN_CLIENT_ID, ATLASSIAN_CLIENT_SECRET | Optional global Atlassian 3LO app for account linking. If unset, each Forge connection can store its own 3LO credentials through the wizard. |
CONFLUENCE_FORGE_INSTALL_URL | Optional 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.
| Variable | Description |
|---|---|
SLACK_CLIENT_ID, SLACK_CLIENT_SECRET | Slack app OAuth credentials. Required to enable the Slack connector. |
SLACK_SIGNING_SECRET | Verifies Event Subscription requests (X-Slack-Signature). |
SLACK_REDIRECT_URI | Optional. 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/slackSee 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.
| Variable | Description |
|---|---|
LINEAR_CLIENT_ID, LINEAR_CLIENT_SECRET | Optional shared Linear OAuth application credentials. When both are set, the wizard skips Register. |
LINEAR_REDIRECT_URI | Optional exact callback override. Defaults to {AUTH_BASE_URL}/api/v1/integrations/linear/callback. |
LINEAR_WEBHOOK_SECRET | Optional 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.
| Variable | Description |
|---|---|
NOTION_CLIENT_ID, NOTION_CLIENT_SECRET | Public integration OAuth credentials. Both are required to enable the connector. |
NOTION_REDIRECT_URI | Optional exact callback override. Defaults to {AUTH_BASE_URL}/api/v1/connectors/notion/oauth/callback. |
NOTION_WEBHOOK_SECRET | Verification 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.
| Variable | Description |
|---|---|
PAGERDUTY_CLIENT_ID, PAGERDUTY_CLIENT_SECRET | Optional shared PagerDuty OAuth application. When unset, save client id and secret on the connection in the wizard. |
PAGERDUTY_REDIRECT_URI | Optional 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| Variable | Description |
|---|---|
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | Traces URL, including /v1/traces. Trace export stays off when this is unset. |
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | Logs URL, including /v1/logs. Unset keeps logs on stdout. |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | Metrics URL, including /v1/metrics. |
OTEL_EXPORTER_OTLP_HEADERS | Optional headers, for example Authorization=Bearer xxx. |
OTEL_SERVICE_NAME | Resource 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_ATTRIBUTES | Extra 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
| Variable | Description |
|---|---|
AUTH_ISSUER | Override the OAuth issuer claim. Defaults to AUTH_BASE_URL. |
AUTH_ALLOWED_ORIGINS | Comma-separated list of allowed CORS origins for auth endpoints. |
OPENWORKFLOW_CONCURRENCY | In-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_CODESEARCH | Optional. 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_CONCURRENCY | Max concurrent Zoekt/SCIP child processes on codesearch, and SCIP HTTP batch size on the worker. Default 2. |
CODESEARCH_INDEX_PIPELINE_CONCURRENCY | Max 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.