robusta-dev · aantn · May 7, 2026
diff --git a/docs/setup-robusta/configuration-secrets.rst b/docs/setup-robusta/configuration-secrets.rst
@@ -64,12 +64,135 @@ You can now reference the environment variable elsewhere in your configuration u
 
 This setup keeps sensitive values out of your Helm files and version control, while still allowing them to be dynamically injected at runtime.
 
+.. _Loading Robusta credentials from secrets:
+
+Loading ``account_id``, ``signing_key``, and the UI token from secrets
+------------------------------------------------------------------------------
+
+After signing up, the Robusta install wizard generates a ``generated_values.yaml`` file with three
+sensitive credentials that are normally written in plain text:
+
+* ``globalConfig.account_id`` — your Robusta account ID
+* ``globalConfig.signing_key`` — used to verify signatures on data sent to the runner
+* ``sinksConfig[].robusta_sink.token`` — the token the Robusta UI sink uses to send findings to the backend; HolmesGPT also uses this token to talk to the backend
+
+To load these from a Kubernetes Secret (or an external secret manager that injects values as env vars,
+e.g. SealedSecrets, External Secrets, Vault, Azure Key Vault), use the steps below.
+
+.. admonition:: Where each value is needed
+    :class: note
+
+    * ``account_id`` and ``signing_key`` are read by the **runner** (via ``globalConfig``).
+    * The UI / sink token is read by the **runner** (via ``sinksConfig`` for the ``robusta_sink``) **and** by **HolmesGPT** (to authenticate to the Robusta backend). The same value must therefore be available as an env var on both pods.
+
+**1. Create a Kubernetes Secret with all three values**
+
+.. code-block:: bash
+
+  kubectl create secret generic my-robusta-secrets \
+    --from-literal=account-id=YOUR_ACCOUNT_ID \
+    --from-literal=signing-key=YOUR_SIGNING_KEY \
+    --from-literal=ui-token=YOUR_UI_TOKEN
+
+**2. Reference the secret on both the runner and Holmes**
+
+The token needs to be exposed as an env var on **both** the runner pod and the Holmes pod. The
+``account_id`` and ``signing_key`` only need to be exposed on the runner.
+
+.. code-block:: yaml
+
+    runner:
+      additional_env_vars:
+        - name: ACCOUNT_ID
+          valueFrom:
+            secretKeyRef:
+              name: my-robusta-secrets
+              key: account-id
+        - name: SIGNING_KEY
+          valueFrom:
+            secretKeyRef:
+              name: my-robusta-secrets
+              key: signing-key
+        - name: ROBUSTA_UI_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: my-robusta-secrets
+              key: ui-token
+
+    # Only required if HolmesGPT is enabled (enableHolmesGPT: true)
+    holmes:
+      additionalEnvVars:
+        - name: ROBUSTA_UI_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: my-robusta-secrets
+              key: ui-token
+
+**3. Reference the env vars from globalConfig and sinksConfig**
+
+.. code-block:: yaml
+
+    globalConfig:
+      account_id: "{{ env.ACCOUNT_ID }}"
+      signing_key: "{{ env.SIGNING_KEY }}"
+
+    sinksConfig:
+      - robusta_sink:
+          name: robusta_ui_sink
+          token: "{{ env.ROBUSTA_UI_TOKEN }}"
+
+After applying these values, the runner and Holmes both pick up the credentials from the secret
+without storing them in plain text anywhere in your Helm values or Git repository.
+
+.. admonition:: Using an external secret manager
+    :class: note
+
+    Any system that injects secrets as environment variables on the pod will work the same way —
+    just use that system's mechanism in place of ``secretKeyRef``. For example, with Azure Key Vault
+    you might write ``value: ui-token@azurekeyvault`` in ``additional_env_vars`` / ``additionalEnvVars``,
+    and the rest of the config (``globalConfig``, ``sinksConfig``) stays identical.
+
+.. admonition:: Non-default API regions (e.g. EU)
+    :class: tip
+
+    If your account is hosted in a non-default region, you also need to point the runner and Holmes at
+    the correct endpoints. Add these to ``runner.additional_env_vars`` and ``holmes.additionalEnvVars``:
+
+    .. code-block:: yaml
+
+        runner:
+          additional_env_vars:
+            - name: ROBUSTA_API_ENDPOINT
+              value: https://api.eu.robusta.dev
+            - name: ROBUSTA_UI_DOMAIN
+              value: https://platform.eu.robusta.dev
+            - name: ROBUSTA_TELEMETRY_ENDPOINT
+              value: https://api.eu.robusta.dev/telemetry
+            - name: RELAY_EXTERNAL_ACTIONS_URL
+              value: https://api.eu.robusta.dev/integrations/generic/actions
+            - name: WEBSOCKET_RELAY_ADDRESS
+              value: wss://relay.eu.robusta.dev
+
+        holmes:
+          additionalEnvVars:
+            - name: ROBUSTA_AI
+              value: "true"
+            - name: ROBUSTA_API_ENDPOINT
+              value: https://api.eu.robusta.dev
+            - name: ROBUSTA_UI_DOMAIN
+              value: https://platform.eu.robusta.dev
+
+    See :ref:`Robusta env var reference` for the full list.
+
 .. _Reading the Robusta UI Token from a secret in HolmesGPT:
 
-Using an Existing Secret for the Robusta UI Token
---------------------------------------------------------
+Using an Existing Secret for the Robusta UI Token (HolmesGPT only)
+---------------------------------------------------------------------------
 
-If you store the Robusta UI token in a Kubernetes secret (instead of directly in Helm values), you need to pass it to HolmesGPT:
+If you only need to inject the UI token into HolmesGPT (for example, the runner already has it via a
+different mechanism), use the snippet below. For the full setup that also covers ``account_id``,
+``signing_key``, and the sink token on the runner, see
+:ref:`Loading Robusta credentials from secrets` above.
 
 .. code-block:: yaml
 

diff --git a/docs/setup-robusta/env-vars.rst b/docs/setup-robusta/env-vars.rst
@@ -0,0 +1,208 @@
+.. _Robusta env var reference:
+
+Environment Variable Reference
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This page lists the environment variables most commonly set when deploying Robusta. It's intended as a
+quick lookup so you don't have to read the source code to understand what each variable does or which
+component reads it.
+
+These variables are set in your Helm values file:
+
+* On the runner, via ``runner.additional_env_vars``
+* On HolmesGPT (when installed via the Robusta Helm chart with ``enableHolmesGPT: true``), via ``holmes.additionalEnvVars``
+
+Both fields accept the standard Kubernetes env var format, so values can be hardcoded or pulled from
+``secretKeyRef`` / ``configMapKeyRef``. See :ref:`Managing Secrets` for examples.
+
+.. note::
+
+    The lists below cover variables a Robusta user typically needs to set. The runner and Holmes both
+    read additional internal/tuning variables that are not listed here. If a variable you need isn't
+    listed, check ``src/robusta/core/model/env_vars.py`` (runner) or ``holmes/common/env_vars.py``
+    (Holmes) in the respective repositories.
+
+Runner (``runner.additional_env_vars``)
+---------------------------------------------
+
+Connecting to the Robusta backend
+==========================================
+
+.. list-table::
+   :widths: 25 50 25
+   :header-rows: 1
+
+   * - Variable
+     - Purpose
+     - Default
+   * - ``ROBUSTA_API_ENDPOINT``
+     - Robusta SaaS API endpoint. Override for non-default regions (e.g. EU).
+     - ``https://api.robusta.dev``
+   * - ``ROBUSTA_UI_DOMAIN``
+     - Robusta UI domain used to build links in notifications.
+     - ``https://platform.robusta.dev``
+   * - ``ROBUSTA_TELEMETRY_ENDPOINT``
+     - Endpoint that receives telemetry pings.
+     - ``https://api.robusta.dev/telemetry``
+   * - ``RELAY_EXTERNAL_ACTIONS_URL``
+     - Endpoint that the runner posts external action requests to.
+     - ``https://api.robusta.dev/integrations/generic/actions``
+   * - ``WEBSOCKET_RELAY_ADDRESS``
+     - WebSocket relay address used for action callbacks from the UI.
+     - ``wss://relay.robusta.dev``
+   * - ``ENABLE_TELEMETRY``
+     - Set to ``false`` to disable telemetry.
+     - ``true``
+
+Credentials (typically referenced from secrets)
+=====================================================
+
+These are usually defined as env vars on the runner pod and then referenced from ``globalConfig`` /
+``sinksConfig`` using the ``{{ env.X }}`` syntax. See
+:ref:`Loading Robusta credentials from secrets` for the full pattern.
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Variable
+     - Purpose
+   * - ``ACCOUNT_ID``
+     - Convention for an env var that holds your Robusta account ID. Referenced from ``globalConfig.account_id`` as ``{{ env.ACCOUNT_ID }}``.
+   * - ``SIGNING_KEY``
+     - Convention for an env var that holds your runner signing key. Referenced from ``globalConfig.signing_key`` as ``{{ env.SIGNING_KEY }}``.
+   * - ``ROBUSTA_UI_TOKEN``
+     - Convention for an env var that holds the Robusta UI sink token. Referenced from ``sinksConfig[].robusta_sink.token`` as ``{{ env.ROBUSTA_UI_TOKEN }}``. The same env var should also be set on Holmes (see below).
+
+.. note::
+
+    The names ``ACCOUNT_ID``, ``SIGNING_KEY``, and ``ROBUSTA_UI_TOKEN`` are conventions — you can pick
+    any env var names you like, as long as the names you set on the pod match the names you reference
+    from ``globalConfig`` / ``sinksConfig``.
+
+Other commonly set runner variables
+=========================================
+
+.. list-table::
+   :widths: 25 50 25
+   :header-rows: 1
+
+   * - Variable
+     - Purpose
+     - Default
+   * - ``HTTP_PROXY`` / ``HTTPS_PROXY``
+     - Forward outbound traffic through an HTTP proxy. See :ref:`Deploying Behind Proxies`.
+     - unset
+   * - ``CERTIFICATE``
+     - Additional CA certificate (base64-encoded). Useful for self-signed corporate proxies.
+     - unset
+   * - ``IS_OPENSHIFT``
+     - Set to ``true`` when running on OpenShift. See :ref:`OpenShift`.
+     - ``false``
+   * - ``CLUSTER_DOMAIN``
+     - Override the cluster's DNS domain.
+     - ``cluster.local``
+
+HolmesGPT (``holmes.additionalEnvVars``)
+-----------------------------------------------
+
+Variables read by HolmesGPT when installed via the Robusta Helm chart (``enableHolmesGPT: true``).
+
+Connecting to the Robusta backend
+==========================================
+
+.. list-table::
+   :widths: 25 50 25
+   :header-rows: 1
+
+   * - Variable
+     - Purpose
+     - Default
+   * - ``ROBUSTA_AI``
+     - Set to ``"true"`` to enable the Robusta-hosted AI integration. Required for users who want Holmes to talk to the Robusta backend.
+     - unset
+   * - ``ROBUSTA_UI_TOKEN``
+     - Robusta UI sink token. Required for Holmes to authenticate to the Robusta backend; should be set to the same token as the runner's ``robusta_sink``.
+     - unset
+   * - ``ROBUSTA_ACCOUNT_ID``
+     - Your Robusta account ID. Usually derived from ``ROBUSTA_UI_TOKEN`` automatically; only set explicitly if instructed by support.
+     - unset
+   * - ``ROBUSTA_API_ENDPOINT``
+     - Robusta SaaS API endpoint. Override for non-default regions.
+     - ``https://api.robusta.dev``
+   * - ``ROBUSTA_UI_DOMAIN``
+     - Robusta UI domain.
+     - ``https://platform.robusta.dev``
+
+LLM and runtime
+========================
+
+.. list-table::
+   :widths: 25 50 25
+   :header-rows: 1
+
+   * - Variable
+     - Purpose
+     - Default
+   * - ``MODEL``
+     - LLM model identifier when using a single-model setup (e.g. ``gpt-4o``). For multi-model setups, configure ``modelList`` in Helm instead.
+     - unset
+   * - ``OPENAI_API_KEY`` / ``AZURE_OPENAI_ENDPOINT`` / ``ANTHROPIC_API_KEY`` / etc.
+     - LLM provider credentials. Set the ones your model requires.
+     - unset
+   * - ``LOG_LEVEL``
+     - Log verbosity (``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``).
+     - ``INFO``
+   * - ``HTTP_PROXY`` / ``HTTPS_PROXY``
+     - Forward outbound traffic through an HTTP proxy.
+     - unset
+   * - ``CERTIFICATE``
+     - Additional CA certificate (base64-encoded).
+     - unset
+   * - ``ENABLE_TELEMETRY``
+     - Set to ``false`` to disable telemetry.
+     - ``false``
+
+Quick reference: which component needs which credential?
+-----------------------------------------------------------------
+
+.. list-table::
+   :widths: 35 25 25 15
+   :header-rows: 1
+
+   * - Setting
+     - Runner
+     - Holmes
+     - Set in
+   * - ``account_id``
+     - ✅
+     - —
+     - ``globalConfig``
+   * - ``signing_key``
+     - ✅
+     - —
+     - ``globalConfig``
+   * - Robusta UI / sink token
+     - ✅
+     - ✅
+     - ``sinksConfig`` (runner) + ``additionalEnvVars`` (Holmes)
+   * - ``ROBUSTA_API_ENDPOINT`` (non-default region)
+     - ✅
+     - ✅
+     - ``additional_env_vars`` / ``additionalEnvVars``
+   * - ``ROBUSTA_UI_DOMAIN`` (non-default region)
+     - ✅
+     - ✅
+     - ``additional_env_vars`` / ``additionalEnvVars``
+   * - ``ROBUSTA_AI=true``
+     - —
+     - ✅
+     - ``additionalEnvVars``
+
+See also
+-----------
+
+* :ref:`Managing Secrets` — how to keep these values out of plain text Helm values
+* :ref:`Deploying Behind Proxies` — proxy-related env vars
+* `Runner env vars in source <https://github.com/robusta-dev/robusta/blob/master/src/robusta/core/model/env_vars.py>`_
+* `HolmesGPT env vars in source <https://github.com/robusta-dev/holmesgpt/blob/master/holmes/common/env_vars.py>`_
diff --git a/docs/setup-robusta/gitops/argocd.rst b/docs/setup-robusta/gitops/argocd.rst
@@ -49,10 +49,15 @@ Example ``generated_values.yaml``:
 ..     - Requires more advanced ArgoCD functions to combine the robusta helm chart with the external ``generated_value.yaml`` file
 
 .. We'll describe the simpler option here. We're currently working on a guide for the more advanced option, contact us if you have questions.
-.. admonition:: Secrets handling
-    :class: note
+.. admonition:: Don't commit secrets in plain text
+    :class: warning
+
+    The ``signing_key``, ``account_id``, and the ``robusta_sink`` ``token`` shown above are
+    sensitive. When using GitOps you typically don't want them in your Git repo as plain text.
 
-    Read this guide about :ref:`Managing Secrets`.
+    See :ref:`Loading Robusta credentials from secrets` for a complete example that loads all three
+    from a Kubernetes Secret (compatible with SealedSecrets, External Secrets, Vault, etc.). For
+    other sensitive Helm values, see :ref:`Managing Secrets`.
 
 
 Configure ArgoCD in the UI

diff --git a/docs/setup-robusta/gitops/flux.rst b/docs/setup-robusta/gitops/flux.rst
@@ -36,10 +36,15 @@ Example ``generated_values.yaml``:
     runner:
       sendAdditionalTelemetry: true
 
-.. admonition:: Secrets handling
-    :class: note
+.. admonition:: Don't commit secrets in plain text
+    :class: warning
+
+    The ``signing_key``, ``account_id``, and the ``robusta_sink`` ``token`` shown above are
+    sensitive. When using GitOps you typically don't want them in your Git repo as plain text.
 
-    Read this guide about :ref:`Managing Secrets`.
+    See :ref:`Loading Robusta credentials from secrets` for a complete example that loads all three
+    from a Kubernetes Secret (compatible with SealedSecrets, External Secrets, Vault, etc.). For
+    other sensitive Helm values, see :ref:`Managing Secrets`.
 
 
 Creating a ``HelmRepository``

diff --git a/docs/setup-robusta/index.rst b/docs/setup-robusta/index.rst
@@ -17,6 +17,7 @@
    upgrade
    tuning-performance
    configuration-secrets
+   env-vars
    openshift
    node-selector
    proxies