# Configuration (https://docs.ctxpipe.ai/docs/self-hosting/configuration)

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](/docs/self-hosting#choose-a-deployment-path): Docker Compose or AWS CDK.
* PostgreSQL with pgvector. Compose uses PostgreSQL 17. AWS CDK
  uses Aurora PostgreSQL 16.
* A graph database. FalkorDB is in the Compose stack.
* ClickHouse 26.10 for the new knowledge store. ClickHouse is in the Compose
  stack. AWS CDK does not deploy it yet.
* 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](/docs/self-hosting/deployment/docker#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

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:pass@smtp.resend.com:465`                                                                                                                                                                                                              |
| `EMAIL_FROM_ADDRESS`  | From address for transactional email, for example `noreply@example.com`                                                                                                                                                                                                               |
| `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`        | Client ID of the GitHub App (sign-in, and the check that a user can access an installation)                                                                                                                                                                                      |
| `GITHUB_CLIENT_SECRET`    | Client secret of the GitHub App                                                                                                                                                                                                                                                  |
| `GITHUB_WEB_URL`          | Optional. The base URL, in place of `https://github.com`, of the GitHub pages that the browser opens for the deployment's App (the authorize page and the install page), when a forwarder serves them. Set it together with `GITHUB_REDIRECT_URI`. Default: `https://github.com` |
| `GITHUB_REDIRECT_URI`     | Optional. The callback URL that the GitHub App lists, when a forwarder serves it. Set it together with `GITHUB_WEB_URL`. Default: `{AUTH_BASE_URL}/.auth/api/v1/auth/callback/github`                                                                                            |
| `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](/docs/self-hosting/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.                                                                                                                                                   |
| `MODEL_VISION_NAME`                                       | Optional. The one OpenRouter model that reads images for the knowledge plane (default `openai/gpt-6.1-terra`). It must take image input and have a ZDR endpoint on OpenRouter. |

See [Model configuration](/docs/self-hosting/models) 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](/docs/self-hosting/graph-databases) for provider support
and tenancy behavior.

## Knowledge store

ClickHouse holds the content of the new knowledge store: the documents, their
sections, and the relations between them. ctxpipe makes this content from the
files of each Workspace repository.

The new knowledge store is off for every organization. A later release
explains how to turn it on.

| Variable                     | Description                                                                                                                                                                                                                                                               |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CLICKHOUSE_URL`             | Required for an organization on the new knowledge store. The ClickHouse HTTP URL with the user, the password, and the database: `http://user:password@host:8123/database`. URL-encode special characters in the password. Each process gets a different user (see below). |
| `CLICKHOUSE_READER_PASSWORD` | Migrations only. The password of the user `ctxpipe_reader`.                                                                                                                                                                                                               |
| `CLICKHOUSE_WRITER_PASSWORD` | Migrations only. The password of the user `ctxpipe_writer`.                                                                                                                                                                                                               |

Give each process its own ClickHouse user in `CLICKHOUSE_URL`:

* **Migrations:** an admin user with SQL access management
  (`access_management`). The migrations create the tables, a row policy for
  each table, and the two users below. Give the admin user to the migrations
  only.
* **Backend:** `ctxpipe_reader`. It can only read the knowledge tables.
* **Worker:** `ctxpipe_writer`. It can read, insert, and delete rows in the
  knowledge tables. It cannot manage users, grants, or row policies.

The migrations create or update a user only when its password is set. Without
the password, the user does not exist and cannot connect. The migrations refuse
the same value for two of the admin, reader, and writer passwords. They also
refuse the reader and writer passwords when the admin password is the Compose
default `ctxpipe`. They store a salted SHA-256 hash of the password. To change
a password, set the new value and run the migrations again. If
`CLICKHOUSE_URL` is not set, the migrations skip ClickHouse.

The knowledge tables move a part to the volume `cold` when its newest row is
30 days old. Thus the `default` storage policy of the server must have the
volumes `hot` and `cold`, or the migrations fail. Compose loads
[`clickhouse-storage.xml`](https://github.com/ctxpipe-ai/ctxpipe/blob/main/apps/backend/src/knowledge-store/clickhouse-storage.xml)
into `/etc/clickhouse-server/config.d/`. On another ClickHouse server, add that
file in the same folder.

The Compose service keeps both volumes on its local disk.

### Keep old parts on S3

This example replaces the disk of the volume `cold` with an S3 bucket behind a
cache disk. Change the bucket URL, the Region, and the cache size:

```xml title="clickhouse-storage-s3.xml"
<clickhouse>
  <storage_configuration>
    <disks>
      <cold_s3>
        <type>s3</type>
        <endpoint>https://example-bucket.s3.us-west-2.amazonaws.com/clickhouse/</endpoint>
        <use_environment_credentials>true</use_environment_credentials>
      </cold_s3>
      <cold>
        <type>cache</type>
        <disk>cold_s3</disk>
        <path>cold</path>
        <max_size>50Gi</max_size>
        <boundary_alignment>131072</boundary_alignment>
      </cold>
    </disks>
    <policies>
      <default>
        <volumes>
          <hot>
            <disk>default</disk>
          </hot>
          <cold>
            <disk>cold</disk>
            <perform_ttl_move_on_insert>0</perform_ttl_move_on_insert>
          </cold>
        </volumes>
        <move_factor>0</move_factor>
      </default>
    </policies>
  </storage_configuration>
</clickhouse>
```

On Compose, mount your file in place of the default file, in a
`docker-compose.override.yml`:

```yaml title="docker-compose.override.yml"
services:
  clickhouse:
    volumes:
      - ./clickhouse-storage-s3.xml:/etc/clickhouse-server/config.d/storage.xml:ro
    environment:
      AWS_ACCESS_KEY_ID: ${CLICKHOUSE_S3_ACCESS_KEY_ID}
      AWS_SECRET_ACCESS_KEY: ${CLICKHOUSE_S3_SECRET_ACCESS_KEY}
```

The search reads small ranges of the vector column, so the example sets
`boundary_alignment` of the cache disk to `131072` (128 KiB). With the default
alignment of 4 MiB, a search that is not in the cache downloads about 1 GiB
from S3 for 46 MiB of data on 1 million sections.

The cache files go to `/var/lib/clickhouse/caches/cold/`. Do not put the cache
path under `/var/lib/clickhouse/disks/`: the image then makes that folder as
`root`, and ClickHouse cannot start.

With `use_environment_credentials`, ClickHouse uses the AWS credentials of its
environment, or the instance role on EC2. Give them read, write, list, and
delete access to the bucket prefix only. Set the S3 disk before the first
start. A part that is already on the local volume `cold` does not move to S3.

### Recover the knowledge store

ClickHouse holds only content that ctxpipe makes from the Workspace
repositories. If you lose the ClickHouse data:

1. Restore a ClickHouse backup, if you have one.

2. Run the migrations again, also after a restore. They make each missing
   table and the users `ctxpipe_reader` and `ctxpipe_writer`. On Compose, set
   the reader and writer passwords in `.env`, then run:

   ```bash
   docker compose --profile deploy run --rm migrate
   ```

3. Delete the index state of the knowledge store in Postgres. Do this also
   after a restore: the backup can be older than the index state, and the
   next run then does not apply the commits between them.

   ```bash
   docker compose exec postgres psql -U ctxpipe -c "DELETE FROM knowledge_state"
   ```

The next hydrate of each Workspace is a full rebuild. Until a Workspace
completes its full rebuild, the graph database answers for it.

## 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`, `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `AGENT_VAULT_SANDBOX_PROXY_HOST`                                | Optional. The host name that sandboxes use to connect to the Agent Vault proxy, when sandboxes cannot use the host of `AGENT_VAULT_ADDR`. Give only a host name: no scheme, no port, and no path. The port is the proxy port that Agent Vault reports (`14322`). Hosted ctxpipe on AWS sets it to the DNS name of the Agent Vault endpoint in the sandbox VPC, because AgentCore sandboxes cannot connect to the private name of the API. That endpoint must forward only the proxy port, never the API port (`14321`): code in a sandbox must not get access to the Agent Vault API. If you do not set it, sandboxes use the address of the `AGENT_VAULT_ADDR` host. Docker Compose and AWS CDK do not set it.                                                                                                                                                                                                                                                                                             |
| `AGENTCORE_RUNTIME_ARN`, `AGENTCORE_RUNTIME_QUALIFIER`          | Required when `SANDBOX_PROVIDER=agentcore`. Hosted ctxpipe uses this provider; 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, `AGENT_VAULT_SANDBOX_PROXY_HOST` when the sandboxes are in a different VPC, 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. |

### Agent Vault rules on AgentCore

With `SANDBOX_PROVIDER=agentcore`, the Agent Vault network allowlist
(`AGENT_VAULT_NETWORK_ALLOWLIST`) holds the backend's own subnets. Thus a
sandbox can send requests to the backend task that runs its turn: to the
model proxy on `PORT`, and to the tool bridge on a port that the kernel
selects. Agent Vault has one allowlist for all its rules. It resolves the
host of a rule again each time it connects. Thus the DNS of a host that a
customer names, for example a plain git repository, can point at a backend
task when Agent Vault connects. This is also possible when the host
resolved to a public address at the time when the backend wrote the rule.

The backend uses the port to keep these rules away from the backend's ports:

* Only a callback rule can use a port other than 443. A callback rule is a
  model proxy or tool bridge rule that the backend makes, and its host is
  the backend's own callback name: `SANDBOX_CALLBACK_HOST`, or
  `ip-<a>-<b>-<c>-<d>.<SANDBOX_CALLBACK_DNS_SUFFIX>` for an address of the
  backend. Each other rule gets port 443.
* The backend refuses each other rule that names another port, for example
  `PORT`, a tool bridge port, or 80 (plain HTTP).
* Agent Vault forwards a request only when a rule matches its host and its
  port, and it connects to that port. A DNS answer cannot change the port.
* Each run vault refuses each host that no rule names.
* When the backend writes a rule, it refuses a host that resolves to an
  address that is not public. If the host does not resolve, the sandbox
  does not start. This check is only a first layer, because the DNS answer
  can change after the check.

The limit: a host that a customer names can still connect to port 443 of
each address in the allowlist. Do not run a service that listens on port
443 in the backend's subnets, and do not add other subnets to the
allowlist. Agent Vault 0.40.2 has no network allowlist for each rule, and no
way to pin a rule to the addresses that the backend checked. With the other
values of `SANDBOX_PROVIDER`, the backend writes the rules as they are.

### Plain git repositories

A plain git repository is a repository that ctxpipe reads with no credential
(see [Linked repositories](/docs/workspaces/linked-repositories#plain-git-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](/docs/self-hosting/deployment/aws#chat-sandbox-host)). |

## 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.

<Callout title="OAuth sign-in is separate">
  `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` are for signing in with GitHub
  and for the one-time authorization that proves access to an installation.
  Use the client ID and secret of the App in `GITHUB_APP_ID`. GitHub App
  credentials are for repository installation and webhook access.
</Callout>

See [GitHub](/docs/self-hosting/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](/docs/self-hosting/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:

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

See [Slack](/docs/self-hosting/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](/docs/self-hosting/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](/docs/self-hosting/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](/docs/self-hosting/pagerduty) for application registration and
verification.

## Observability

Telemetry is off until you set it. ctxpipe does not ship a collector 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.

```bash
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 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 with the GenAI semantic conventions:
`gen_ai.operation.name`, `gen_ai.request.model`, `gen_ai.usage.input_tokens`,
`gen_ai.usage.output_tokens`, and `gen_ai.usage.cost` (USD, when the model
gateway reports it). A span also holds the prompt and the output text in
`gen_ai.input.messages` and `gen_ai.output.messages`. The backend logs never
hold them. `@ctxpipe/aws-cdk` takes one base `otel.endpoint`
and appends `/v1/traces`, `/v1/logs`, and `/v1/metrics`. See
[AWS](/docs/self-hosting/deployment/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 sets 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`. At most one of them runs a SCIP indexer at a time. |
| `CODESEARCH_INDEX_PIPELINE_CONCURRENCY` | Max distinct repos with in-flight OpenWorkflow index-phase HTTP (clone included). Default `2`. Codesearch returns 429 when full.                                 |

## Related pages

<Cards>
  <Card title="Production readiness" href="/docs/self-hosting/production-readiness" description="Preflight checks before exposing a deployment." />

  <Card title="Operations" href="/docs/self-hosting/operations" description="Runtime checks, logs, and backups." />

  <Card title="Upgrades" href="/docs/self-hosting/upgrades" description="Upgrade and rollback process." />
</Cards>
