Baserow AI-Assistant: Quick DevOps Setup

This guide shows how to configure the AI assistant’s provider and model in Baserow and optionally enable knowledge-base lookups through an embeddings server.

1) Core concepts

  • The assistant is built on pydantic-ai — a Python agent framework that supports multiple LLM providers out of the box.
  • An instance administrator configures providers and chooses one Kuma model under Admin tools → AI providers → AI features. A workspace admin can inherit that choice, select another model available to Kuma, or disable Kuma in the workspace’s Settings → AI providers.
  • BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL and its UDSPY_LM_MODEL alias are deprecated. They remain compatibility fallbacks while the Kuma selection is unconfigured or invalid. An explicit instance or workspace disable remains authoritative.
  • The assistant has been mostly tested with the gpt-oss-120b family. Other models can work as well.

2) Minimal enablement

For a fresh setup, add a provider and its models under Admin tools → AI providers or a workspace’s Settings → AI providers; see where to configure them. On each model, choose whether it is available to Kuma, AI Fields, AI Agent actions, or any combination of them, then select the Kuma model in the AI features section. Availability permits a feature to choose a model; it does not force AI Fields or AI Agent actions to use Kuma’s model. Use Test model to check every selected feature. AI Fields and AI Agent actions check for a text response, while Kuma also checks tool calling.

Changing a model that is already in use is confirmed, not applied silently. Disabling or deleting a model, unchecking one of its features, or renaming its identifier first reports how many AI Fields and AI Agent actions use it, and applies the change once confirmed: those consumers store the provider type and the model identifier rather than a reference to the model, so they keep the old selection and stop working until they are repointed. Counts are per provider type and identifier, so an instance model and a workspace model sharing an identifier report the same consumers. The Kuma selection is a real reference instead, so disabling or deleting the model, or unchecking Kuma, is refused while it is selected as the Kuma model: repoint that selection first, in the AI features section of the scope that holds it. Renaming is allowed and the Kuma selection follows the model to its new identifier. A consumer left on a model that is disabled or gone keeps showing its saved provider and model, marked unavailable, so it can be found and repointed.

For an existing installation, see Upgrading to Baserow 2.4. The upgrade imports legacy provider settings automatically. Applications published before the upgrade keep the settings copied into them at publish time, and explicit integration overrides keep their own credentials; both need separate review before they can use centrally managed credentials. Republishing a site or workflow also deploys its current draft changes.

The import does not cover the deprecated Kuma model selector or the provider-native credentials used by Kuma. The assistant therefore stays on its legacy fallback until an administrator configures the same provider connection in the database, marks and tests a model for Kuma, and explicitly selects it. A database selection is authoritative, so verify its credentials and endpoint before switching. To roll back that selection, choose Use environment model (deprecated), which also displays the configured model, in the instance AI feature settings. The choice is disabled when neither BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL nor the deprecated UDSPY_LM_MODEL fallback provides a model to the web-frontend process, which is where that option is rendered: setting the variable on the backend alone leaves the option disabled while the backend fallback still resolves. Choosing Disabled deliberately keeps Kuma off.

When using the legacy fallback with Docker Compose or multiple services, set BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL in both backend and frontend services.

# Required only for the legacy fallback
# Deprecated; choose the Kuma model under Admin tools → AI providers → AI features.
BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL=openai:gpt-5.2
OPENAI_API_KEY=your_api_key

# Optional - adjust LLM temperature (default: 0.3)
BASEROW_ENTERPRISE_ASSISTANT_LLM_TEMPERATURE=0.3

About temperature:

  • Controls randomness in the main assistant’s LLM responses.
  • Default: 0.3 (focused, consistent responses)
  • Higher values (depending on the model) = more creative/varied responses.
  • Lower values (e.g., 0-0.1) = more analytical responses. Note that even with temperature of 0.0, the results will not be fully deterministic.

3) Legacy fallback provider presets

These presets retain compatibility for existing environment-based setups. Their BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL selector is deprecated; use provider administration and an explicit Kuma selection when the connection is representable there. Vertex AI, and Bedrock through the server’s IAM role or instance profile, do not have an equivalent database provider configuration, so those paths must keep their verified environment fallback. Do not remove a working fallback before a replacement is available and tested.

Choose one provider block for a fallback that is still needed. pydantic-ai’s native credential and connection variables, such as OPENAI_API_KEY, GROQ_API_KEY, AWS credentials, and OPENAI_BASE_URL, remain supported; they are separate from the deprecated Baserow model selector.

OpenAI / OpenAI-compatible

BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL=openai:gpt-5.2
OPENAI_API_KEY=your_api_key
# Optional: point to an alternative OpenAI-compatible endpoint
OPENAI_BASE_URL=https://eu.api.openai.com/v1
# or
OPENAI_BASE_URL=https://<your-resource-name>.openai.azure.com

Anthropic

BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL=anthropic:claude-sonnet-4-20250514
ANTHROPIC_API_KEY=your_api_key

AWS Bedrock

Bedrock with an IAM access key or a Bedrock API key can be added in AI providers instead. Keep this fallback only for credentials that come from the server itself.

pydantic-ai supports two authentication methods for Bedrock. Use whichever matches your setup.

Option A — Standard AWS credentials (boto3)

BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL=bedrock:openai.gpt-oss-120b-1:0
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_DEFAULT_REGION=eu-central-1

Any boto3-compatible credential method works: env vars, IAM roles, instance profiles, ~/.aws/credentials, etc.

Option B — Bedrock bearer token

BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL=bedrock:openai.gpt-oss-120b-1:0
AWS_BEARER_TOKEN_BEDROCK=your_bearer_token
AWS_DEFAULT_REGION=eu-central-1

Groq

BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL=groq:openai/gpt-oss-120b
GROQ_API_KEY=your_api_key

Google (Gemini)

BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL=google:gemini-3.6-flash
GOOGLE_API_KEY=your_api_key

Create the key in Google AI Studio. For Vertex AI, use the google-cloud prefix instead: GOOGLE_API_KEY is then treated as a Vertex AI Express Mode key, while project-based access uses Application Default Credentials.

Ollama

BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL=ollama:gpt-oss:120b
# Point to your Ollama instance (defaults to http://localhost:11434/v1)
OLLAMA_BASE_URL=http://localhost:11434/v1

pydantic-ai auto-detects the provider from the model prefix and routes requests accordingly.

4) Knowledge-base lookup

If your deployment method doesn’t auto-provision embeddings, run the Baserow embeddings service and point Baserow at it.

For developers using Docker Compose: See embeddings-server.md for setup instructions.

Run the embeddings container

docker run -d --name baserow-embeddings -p 80:80 baserow/embeddings:latest

Point Baserow to it

BASEROW_EMBEDDINGS_API_URL=http://your-embedder-service
# e.g., http://localhost if you mapped -p 80:80 locally
# Then restart Baserow and allow migrations to run.

After restart and migrations, knowledge-base lookup will be available.

5) Troubleshooting

The assistant doesn’t appear or doesn’t work

If the assistant is not visible in the sidebar or doesn’t work, verify that:

Use one of these configurations:

  1. Select a usable Kuma model under Admin tools → AI providers → AI features and make sure its model test passes; or
  2. For an existing compatibility setup, leave the Kuma selection unconfigured and set the deprecated BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL in both backend and frontend services, with its provider credentials available to the backend.

An explicit Kuma disable does not use the legacy fallback.

Verifying legacy environment variables in development

To check if the variables are set correctly in development, from the host run:

# Check backend
just dcd run --rm backend bash -c env | grep LLM_MODEL
just dcd run --rm backend bash -c env | grep API_KEY

# Check frontend
just dcd run --rm web-frontend bash -c env | grep LLM_MODEL

Both commands must return the same value for BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL. If either is missing or they differ, update your environment configuration and restart the services.

6) Supported models

OpenAI, Anthropic, AWS Bedrock, Groq, Gemini/Vertex AI and any OpenAI-compatible endpoint (Azure, DeepSeek, Fireworks, LiteLLM, Perplexity, Together AI, etc.).

7) Framework change: UDSPy to pydantic-ai

The assistant previously used UDSPy as its agent framework. It now uses pydantic-ai. Most environment variables are unchanged or bridged for backward compatibility.

Environment compatibility

Variable Notes
BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL Deprecated. Kuma uses this model until you make a model available to Kuma and select it under Admin tools → AI providers → AI features. It is also used when that selection becomes unavailable, but not when Kuma is set to Disabled there. Both provider/model and provider:model formats are accepted.
BASEROW_ENTERPRISE_ASSISTANT_LLM_TEMPERATURE Still supported. Overrides the orchestrator temperature when set.
OPENAI_API_KEY Unchanged.
GROQ_API_KEY Unchanged.
AWS_BEARER_TOKEN_BEDROCK Still works — pydantic-ai supports Bedrock bearer token auth natively.

Bridged for backward compatibility

Old variable Equivalent Notes
UDSPY_LM_MODEL Kuma model under Admin tools → AI providers → AI features Deprecated. Used only when BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL is not set. Selecting a Kuma model in AI features replaces it; renaming it to BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL does not.
UDSPY_LM_API_KEY API key of the provider in Admin tools → AI providers Deprecated. Only read while Kuma uses its environment model. If you still need that, use the provider’s own variable instead, such as OPENAI_API_KEY or GROQ_API_KEY.
UDSPY_LM_OPENAI_COMPATIBLE_BASE_URL Base URL (OpenAI) or Host (Ollama) of the provider in Admin tools → AI providers Deprecated. Only read while Kuma uses its environment model. If you still need that, use OPENAI_BASE_URL or OLLAMA_BASE_URL instead.
AWS_REGION_NAME AWS_DEFAULT_REGION Still works; bridged automatically.

New variables

Variable Notes
OPENAI_BASE_URL Preferred replacement for UDSPY_LM_OPENAI_COMPATIBLE_BASE_URL.
AWS_DEFAULT_REGION Preferred replacement for AWS_REGION_NAME.
OLLAMA_BASE_URL Replaces UDSPY_LM_OPENAI_COMPATIBLE_BASE_URL for Ollama. Defaults to http://localhost:11434/v1.
ANTHROPIC_API_KEY New provider — Anthropic models are now supported.
AI providersBackend API