Skip to main content
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.
AI features are part of the Enterprise Edition. See AI Features for what the toggle unlocks and how your data is handled.
Wiring up an LLM takes two steps:
1

Point the instance at a model

Set AI_PROVIDER, AI_MODEL, and the credentials for that provider as environment variables, then restart your containers.
2

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.

​
Choosing a provider

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

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

​
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.
  • 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.
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.
Structured outputs are a separate capability from authentication. Check that your gateway supports them before setting AI_OPENAI_COMPATIBLE_SUPPORTS_STRUCTURED_OUTPUTS=1.
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.

​
Google Cloud

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 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.
Formbricks uses Google Cloud naming here, even though the underlying SDK still talks to Vertex AI endpoints for Gemini model access.

​
Azure

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.

​
AWS Bedrock

​
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.
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.
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:
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.