Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

BOT-1921: Document additional Metabot environment variables (#79662)

Andrei Simionescuc30815f9107d
diff --git a/docs/configuring-metabase/environment-variables.md b/docs/configuring-metabase/environment-variables.md
index 67963429ed3..5b024127284 100644
--- a/docs/configuring-metabase/environment-variables.md
+++ b/docs/configuring-metabase/environment-variables.md
@@ -1572,6 +1572,28 @@ Custom CORS origins for self-hosted MCP clients, space-separated.
Popular MCP clients enabled for CORS, stored as CSV client keys (e.g. claude, vscode).
+### `MB_METABOT_ADVANCED_PERMISSIONS`
+
+> Only available on Metabase [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans.
+
+- Type: boolean
+- Default: `false`
+- [Exported as](../installation-and-operation/serialization.md): `metabot-advanced-permissions`.
+- [Configuration file name](./config-file.md): `metabot-advanced-permissions`
+
+Whether the AI feature access admin page shows granular, per-tool group permissions instead of a single on/off toggle per group.
+
+### `MB_METABOT_CHAT_SYSTEM_PROMPT`
+
+> Only available on Metabase [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans.
+
+- Type: string
+- Default: ``
+- [Exported as](../installation-and-operation/serialization.md): `metabot-chat-system-prompt`.
+- [Configuration file name](./config-file.md): `metabot-chat-system-prompt`
+
+Custom instructions appended to Metabot's system prompt for the chat experience (the AI sidebar and embedded Metabot).
+
### `MB_METABOT_ENABLED`
- Type: boolean
@@ -1581,6 +1603,72 @@ Popular MCP clients enabled for CORS, stored as CSV client keys (e.g. claude, vs
Whether Metabot is enabled for regular usage.
+### `MB_METABOT_ICON`
+
+> Only available on Metabase [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans.
+
+- Type: string
+- Default: `metabot`
+- [Exported as](../installation-and-operation/serialization.md): `metabot-icon`.
+- [Configuration file name](./config-file.md): `metabot-icon`
+
+The icon for Metabot. Set to `metabot` for the default icon, or a data URI for a custom uploaded image (up to 1MB).
+
+### `MB_METABOT_LIMIT_RESET_RATE`
+
+> Only available on Metabase [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans.
+
+- Type: keyword
+- Default: `monthly`
+- [Exported as](../installation-and-operation/serialization.md): `metabot-limit-reset-rate`.
+- [Configuration file name](./config-file.md): `metabot-limit-reset-rate`
+
+How often Metabot usage limits reset: `daily`, `weekly`, or `monthly`.
+
+### `MB_METABOT_LIMIT_UNIT`
+
+> Only available on Metabase [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans.
+
+- Type: keyword
+- Default: `tokens`
+- [Exported as](../installation-and-operation/serialization.md): `metabot-limit-unit`.
+- [Configuration file name](./config-file.md): `metabot-limit-unit`
+
+The unit used for Metabot usage limits: `tokens` or `messages`.
+
+### `MB_METABOT_NAME`
+
+> Only available on Metabase [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans.
+
+- Type: string
+- Default: `Metabot`
+- [Exported as](../installation-and-operation/serialization.md): `metabot-name`.
+- [Configuration file name](./config-file.md): `metabot-name`
+
+The display name for Metabot, shown throughout the Metabase UI.
+
+### `MB_METABOT_NLQ_SYSTEM_PROMPT`
+
+> Only available on Metabase [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans.
+
+- Type: string
+- Default: ``
+- [Exported as](../installation-and-operation/serialization.md): `metabot-nlq-system-prompt`.
+- [Configuration file name](./config-file.md): `metabot-nlq-system-prompt`
+
+Custom instructions appended to Metabot's system prompt for the natural language query (AI exploration) experience.
+
+### `MB_METABOT_QUOTA_REACHED_MESSAGE`
+
+> Only available on Metabase [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans.
+
+- Type: string
+- Default: `You have reached your AI usage limit for the current period. Please contact your administrator.`
+- [Exported as](../installation-and-operation/serialization.md): `metabot-quota-reached-message`.
+- [Configuration file name](./config-file.md): `metabot-quota-reached-message`
+
+The message shown to users when they reach their usage quota.
+
### `MB_METABOT_RECENT_VIEWS_ENABLED`
- Type: boolean
@@ -1588,6 +1676,17 @@ Whether Metabot is enabled for regular usage.
Whether the user's recently viewed items are included in the Metabot system prompt.
+### `MB_METABOT_SHOW_ILLUSTRATIONS`
+
+> Only available on Metabase [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans.
+
+- Type: boolean
+- Default: `true`
+- [Exported as](../installation-and-operation/serialization.md): `metabot-show-illustrations`.
+- [Configuration file name](./config-file.md): `metabot-show-illustrations`
+
+Whether to show Metabot illustrations in the UI.
+
### `MB_METABOT_SLACK_SIGNING_SECRET`
- Type: string
@@ -1596,6 +1695,17 @@ Whether the user's recently viewed items are included in the Metabot system prom
Signing secret for verifying requests from the Metabot Slack app.
+### `MB_METABOT_SQL_SYSTEM_PROMPT`
+
+> Only available on Metabase [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans.
+
+- Type: string
+- Default: ``
+- [Exported as](../installation-and-operation/serialization.md): `metabot-sql-system-prompt`.
+- [Configuration file name](./config-file.md): `metabot-sql-system-prompt`
+
+Custom instructions appended to Metabot's system prompt for the SQL generation experience.
+
### `MB_MFA_CHALLENGE_SIGNING_KEY`
- Type: string
diff --git a/enterprise/backend/src/metabase_enterprise/metabot/settings.clj b/enterprise/backend/src/metabase_enterprise/metabot/settings.clj
index 92deb028259..c41e0d06273 100644
--- a/enterprise/backend/src/metabase_enterprise/metabot/settings.clj
+++ b/enterprise/backend/src/metabase_enterprise/metabot/settings.clj
@@ -7,13 +7,13 @@
(def ^:private valid-limit-units #{:tokens :messages})
(defsetting metabot-limit-unit
- (deferred-tru "The unit used for metabot usage limits.")
+ (deferred-tru "The unit used for Metabot usage limits: `tokens` or `messages`.")
:type :keyword
:default :tokens
:visibility :settings-manager
:encryption :no
:export? true
- :doc false
+ :feature :ai-controls
:setter (fn [new-value]
(let [v (some-> new-value keyword)]
(when (and v (not (contains? valid-limit-units v)))
@@ -25,13 +25,13 @@
(def ^:private valid-reset-rates #{:daily :weekly :monthly})
(defsetting metabot-limit-reset-rate
- (deferred-tru "How often metabot usage limits reset.")
+ (deferred-tru "How often Metabot usage limits reset: `daily`, `weekly`, or `monthly`.")
:type :keyword
:default :monthly
:visibility :settings-manager
:encryption :no
:export? true
- :doc false
+ :feature :ai-controls
:setter (fn [new-value]
(let [v (some-> new-value keyword)]
(when (and v (not (contains? valid-reset-rates v)))
@@ -47,13 +47,13 @@
:visibility :settings-manager
:encryption :no
:export? true
- :doc false)
+ :feature :ai-controls)
(defsetting metabot-advanced-permissions
- (deferred-tru "Whether AI feature access uses advanced group-level permissions.")
+ (deferred-tru "Whether the AI feature access admin page shows granular, per-tool group permissions instead of a single on/off toggle per group.")
:type :boolean
:default false
:visibility :admin
:encryption :no
:export? true
- :doc false)
+ :feature :ai-controls)
diff --git a/src/metabase/metabot/settings.clj b/src/metabase/metabot/settings.clj
index 25628dd4278..0403012893e 100644
--- a/src/metabase/metabot/settings.clj
+++ b/src/metabase/metabot/settings.clj
@@ -27,24 +27,22 @@
:export? true)
(defsetting metabot-name
- (deferred-tru "The display name for Metabot.")
+ (deferred-tru "The display name for Metabot, shown throughout the Metabase UI.")
:type :string
:default "Metabot"
:visibility :public
:encryption :no
:export? true
- :feature :ai-controls
- :doc false)
+ :feature :ai-controls)
(defsetting metabot-icon
- (deferred-tru "The icon for Metabot.")
+ (deferred-tru "The icon for Metabot. Set to `metabot` for the default icon, or a data URI for a custom uploaded image (up to 1MB).")
:type :string
:default "metabot"
:visibility :public
:encryption :no
:export? true
- :feature :ai-controls
- :doc false)
+ :feature :ai-controls)
(defsetting metabot-show-illustrations
(deferred-tru "Whether to show Metabot illustrations in the UI.")
@@ -53,38 +51,34 @@
:visibility :public
:encryption :no
:export? true
- :feature :ai-controls
- :doc false)
+ :feature :ai-controls)
(defsetting metabot-chat-system-prompt
- (deferred-tru "Custom system prompt for the Metabot chat (sidebar AI chat) experience.")
+ (deferred-tru "Custom instructions appended to Metabot''s system prompt for the chat experience (the AI sidebar and embedded Metabot).")
:type :string
:default ""
:visibility :admin
:encryption :no
:export? true
- :feature :ai-controls
- :doc false)
+ :feature :ai-controls)
(defsetting metabot-nlq-system-prompt
- (deferred-tru "Custom system prompt for the natural language query (AI exploration) experience.")
+ (deferred-tru "Custom instructions appended to Metabot''s system prompt for the natural language query (AI exploration) experience.")
:type :string
:default ""
:visibility :admin
:encryption :no
:export? true
- :feature :ai-controls
- :doc false)
+ :feature :ai-controls)
(defsetting metabot-sql-system-prompt
- (deferred-tru "Custom system prompt for the SQL generation experience.")
+ (deferred-tru "Custom instructions appended to Metabot''s system prompt for the SQL generation experience.")
:type :string
:default ""
:visibility :admin
:encryption :no
:export? true
- :feature :ai-controls
- :doc false)
+ :feature :ai-controls)
(defsetting embedded-metabot-enabled?
(deferred-tru "Whether Metabot is enabled for embedding.")