> ## Documentation Index
> Fetch the complete documentation index at: https://formbricks.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Features

> Connect an LLM to your instance and enable AI-powered helpers like survey translation and AI chart creation.

A single organization toggle unlocks AI-assisted survey translation and AI chart creation across the app.
Formbricks runs fine without AI — nothing is enabled until you connect a model.

<Note>
  AI features are part of the [Enterprise Edition](/docs/self-hosting/advanced/license). See [AI
  Features](/docs/platform/features/ai-features) for what the toggle unlocks and how your data is handled.
</Note>

Wiring up an LLM takes two steps:

<Steps>
  <Step title="Point the instance at a model">
    Set `AI_PROVIDER`, `AI_MODEL`, and the credentials for that provider as environment variables, then
    restart your containers.
  </Step>

  <Step title="Turn AI on for the organization">
    In the app, go to **Settings → Organization → General → Smart functionality (AI)** and enable the toggle.
    Only Owners and Managers can change it.
  </Step>
</Steps>

## Choosing a provider

`AI_PROVIDER` accepts four values. Set only the variables for the provider you use — the rest can be omitted.

| `AI_PROVIDER` | Runs on |
| - | - |
| `openai-compatible` | Any OpenAI-compatible `/v1` endpoint — Qwen/vLLM and friends. The self-hosted path. |
| `google` | Google Cloud, for Gemini models. |
| `azure` | Azure OpenAI / Foundry. |
| `aws` | Amazon Bedrock. |

## OpenAI-compatible (self-hosted)

The supported self-hosted path is Qwen served by vLLM behind an OpenAI-compatible `/v1` endpoint. Docker Compose
and the Helm chart can both deploy that runtime for you — both paths are disabled by default and require
GPU-capable hosts.

### Docker Compose

The Docker stack deploys the Qwen/vLLM runtime through an opt-in Compose profile. It needs a GPU-capable Docker
host with the NVIDIA Container Toolkit installed.

```bash theme={null}
COMPOSE_PROFILES=qwen
AI_PROVIDER=openai-compatible
AI_MODEL=qwen3-14b-awq
AI_OPENAI_COMPATIBLE_BASE_URL=http://vllm:8000/v1
AI_OPENAI_COMPATIBLE_PROVIDER_NAME=vllm
AI_OPENAI_COMPATIBLE_SUPPORTS_STRUCTURED_OUTPUTS=1
```

If you use the optional taxonomy service and want it to share the bundled Qwen runtime, start Docker Compose with
`COMPOSE_PROFILES=qwen,taxonomy` and point `TAXONOMY_LLM_BASE_URL` at `http://vllm:8000/v1`.

### Kubernetes Helm

The Formbricks Helm chart deploys the same runtime on GPU-capable Kubernetes nodes.

```yaml theme={null}
llm:
  enabled: true
```

When `llm.enabled` is true, the chart deploys the vLLM router and Qwen serving engine. By default it also points
the Formbricks app at the in-cluster OpenAI-compatible endpoint by injecting the required `AI_*` environment
variables.

Set `llm.autoConfigureApp=false` if you want the chart to deploy Qwen/vLLM but prefer to configure the app
provider manually.

### Your own endpoint

To use an endpoint you already run, do not enable the bundled runtime — keep the `qwen` Compose profile off, or
`llm.enabled=false` in Helm. Point `AI_OPENAI_COMPATIBLE_BASE_URL` at your endpoint and add
`AI_OPENAI_COMPATIBLE_API_KEY` if it requires one.

`AI_PROVIDER` and `AI_MODEL` are always required. `AI_OPENAI_COMPATIBLE_BASE_URL` is the only variable specific
to this provider that you must set, and it has to be a valid HTTP(S) URL.

<Warning>
  Use an `https://` endpoint whenever you set `AI_OPENAI_COMPATIBLE_API_KEY`. Formbricks accepts a plain `http://`
  URL, so nothing stops you sending that key — and every prompt — in cleartext. Plain HTTP is only appropriate for
  an endpoint that takes no credentials and is unreachable from outside your network, such as the bundled
  `http://vllm:8000/v1` on the internal Compose network.
</Warning>

### Behind an OAuth2 gateway

Some gateways in front of a model do not accept a static API key. They issue short-lived access tokens through the
OAuth2 client-credentials flow instead: Formbricks exchanges a client ID and secret for a token at the gateway's
token endpoint, and sends that token with every model request. Set `AI_OPENAI_COMPATIBLE_AUTH_MODE` and Formbricks
fetches the token for you, refreshes it shortly before it expires, and requests a new one if the gateway rejects
it — you never paste a token.

```bash theme={null}
AI_PROVIDER=openai-compatible
AI_MODEL=your-model
AI_OPENAI_COMPATIBLE_BASE_URL=https://gateway.example.internal/v1
AI_OPENAI_COMPATIBLE_AUTH_MODE=oauth2-client-credentials
AI_OPENAI_COMPATIBLE_OAUTH_TOKEN_URL=https://gateway.example.internal/oauth/token
AI_OPENAI_COMPATIBLE_OAUTH_CLIENT_ID=formbricks
AI_OPENAI_COMPATIBLE_OAUTH_CLIENT_SECRET=your-client-secret
# Optional
AI_OPENAI_COMPATIBLE_OAUTH_SCOPE="llm.invoke"
AI_OPENAI_COMPATIBLE_OAUTH_AUTH_STYLE=basic
AI_OPENAI_COMPATIBLE_OAUTH_EXTRA_PARAMS_JSON={"audience":"https://gateway.example.internal"}
```

* `AI_OPENAI_COMPATIBLE_OAUTH_AUTH_STYLE` decides where the client credentials go. `basic`, the default and the
  OAuth2 standard, sends them in the `Authorization` header of the token request. `post` sends them in the form
  body instead, which some gateways require.
* `AI_OPENAI_COMPATIBLE_OAUTH_SCOPE` is a space-separated list of scopes, if your gateway asks for any.
* `AI_OPENAI_COMPATIBLE_OAUTH_EXTRA_PARAMS_JSON` adds string parameters to the token request, such as the
  `audience` or `resource` some identity providers expect.
* Leave `AI_OPENAI_COMPATIBLE_API_KEY` unset. Formbricks refuses to start when both are configured, so there is
  only ever one source of credentials.

If the gateway rejects the credentials, survey generation tells the user to ask an administrator to check the AI
provider configuration, and the server log records the failure without the secret or the token.

<Note>
  If the token endpoint or the gateway uses a certificate from a private CA, set
  `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` on the Formbricks container. No Formbricks setting is needed. Mutual TLS
  (client certificates) is not supported.
</Note>

<Note>
  Structured outputs are a separate capability from authentication. Check that your gateway supports them before
  setting `AI_OPENAI_COMPATIBLE_SUPPORTS_STRUCTURED_OUTPUTS=1`.
</Note>

<Warning>
  In this mode both `AI_OPENAI_COMPATIBLE_OAUTH_TOKEN_URL` and `AI_OPENAI_COMPATIBLE_BASE_URL` must be
  `https://` URLs: the client secret goes to the first on every token request and the access token to the
  second on every model request, so Formbricks refuses to start with a plain `http://` endpoint for either.
  The one exception is `localhost`, for local development against a mock gateway.
</Warning>

## Google Cloud

```bash theme={null}
AI_PROVIDER=google
AI_MODEL=gemini-3.5-flash
AI_GOOGLE_CLOUD_PROJECT=your-project-id
AI_GOOGLE_CLOUD_LOCATION=global
```

Formbricks passes `AI_GOOGLE_CLOUD_LOCATION` through as given and enforces no list of its own: `us` and `eu`
are sent to their multi-region endpoints, and every other value — `global` and regional locations such as
`europe-west3` — uses the SDK default endpoint. Which locations actually serve your model depends on Google's
availability for that model and your serving mode, so check the
[model page](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-5-flash) before picking
one for data-residency reasons. `global` is the safe default.

Credentials are optional. If the container already has Application Default Credentials, leave both credential
variables unset. Otherwise pick one:

* `AI_GOOGLE_CLOUD_APPLICATION_CREDENTIALS` — mount the service account key file into the container and set this
  to its path, for example `/run/secrets/google-cloud.json`.
* `AI_GOOGLE_CLOUD_CREDENTIALS_JSON` — the entire contents of that key file, as a single-line JSON string.
  Formbricks parses this value, so paste the whole file: a truncated or hand-edited value fails as invalid JSON.

<Note>
  Formbricks uses Google Cloud naming here, even though the underlying SDK still talks to Vertex AI endpoints for
  Gemini model access.
</Note>

## Azure

```bash theme={null}
AI_PROVIDER=azure
AI_MODEL=your-deployment-name
AI_AZURE_API_KEY=your-api-key
AI_AZURE_RESOURCE_NAME=your-resource
```

`AI_MODEL` is the deployment name, not the base model name. `AI_AZURE_API_VERSION` defaults to `v1`.

Provide either `AI_AZURE_RESOURCE_NAME` or `AI_AZURE_BASE_URL` — the base URL wins when both are set. If you set
the base URL, end it at `/openai` and do not append `/v1`: the Azure SDK adds the version segment itself, so
`https://your-resource.openai.azure.com/openai/v1` produces requests against `/openai/v1/v1/…` and fails.

```bash theme={null}
# Equivalent to the resource name above
AI_AZURE_BASE_URL=https://your-resource.openai.azure.com/openai
```

## AWS Bedrock

```bash theme={null}
AI_PROVIDER=aws
AI_MODEL=eu.anthropic.claude-sonnet-4-5-20250929-v1:0
AI_AWS_REGION=eu-central-1
AI_AWS_ACCESS_KEY_ID=your-access-key-id
AI_AWS_SECRET_ACCESS_KEY=your-secret-access-key
# Only for temporary credentials
AI_AWS_SESSION_TOKEN=your-session-token
```

## External providers on Kubernetes

Keep `llm.enabled=false` when you use Google Cloud, Azure, AWS Bedrock, or your own OpenAI-compatible runtime.
Configure those providers with `deployment.env` in your Helm values or with environment variables in your
deployment platform.

## Verifying the setup

Restart your containers after changing any of these variables, then open **Settings → Organization → General**.
While the instance is not configured, the AI toggle stays disabled and the page says so — the setting cannot be
turned on from the UI until the environment variables are in place.

<Warning>
  An enabled toggle only means the variables are present and well-formed. Formbricks does not call your provider
  to check it: an unreachable base URL, a wrong API key, or a deployment name that does not exist all pass this
  check and fail on the first real request.
</Warning>

So finish by exercising the model once — translate a survey into a second language, or ask the AI chart builder
for a chart. If that request fails while the toggle is on, the credentials or the endpoint are wrong, not the
configuration shape.

If the toggle stays disabled after a restart, check the app logs:

```bash theme={null}
docker compose logs formbricks | grep -i "ai"
```

The usual causes are `AI_MODEL` left unset, credentials that do not match the chosen `AI_PROVIDER`, or an
`AI_GOOGLE_CLOUD_CREDENTIALS_JSON` value that is not valid JSON.

The full list of `AI_*` variables, including the optional ones, is in the [environment variables
reference](/docs/self-hosting/configuration/environment-variables).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.