.. _client-envs:

Client Environment Variables
=============================

The Scaleout Edge Python client can be configured through environment variables. These are defined in ``scaleout-util`` and apply when running a client via the :ref:`scaleout-cli` or the Python SDK.

.. list-table::
   :header-rows: 1
   :widths: 40 15 45

   * - Variable
     - Default
     - Description
   * - ``SCALEOUT_ARCHIVE_DIR``
     - ``.scaleout/archive``
     - Directory where the client stores archived model checkpoints and artifacts.
   * - ``SCALEOUT_AUTH_SCHEME``
     - ``Bearer``
     - HTTP authentication scheme used in the ``Authorization`` header when calling the API.
   * - ``SCALEOUT_CONNECT_API_SECURE``
     - ``true``
     - Whether to connect to the API over TLS (``true``/``false``). Set to ``false`` for local non-TLS deployments.
   * - ``SCALEOUT_GRPC_SECURE``
     - *(unset)*
     - Whether to connect to the combiner over a TLS (secure) gRPC channel (``true``/``false``), independent of the port number. When unset, the client uses the TLS mode the combiner reports on assignment, and TLS if the combiner doesn't report one (older combiners). When set, the combiner can still upgrade a ``false`` to TLS, but never downgrade a ``true``. See :ref:`Connecting clients over gRPC <client-grpc-tls>`.
   * - ``SCALEOUT_GRPC_ROOT_CERT_PATH``
     - *(unset)*
     - Path to a PEM root certificate used to verify the combiner's TLS certificate. Required when the combiner uses a self-signed or private-CA certificate; leave unset to use the system trust store (e.g. for publicly-trusted certificates).
   * - ``SCALEOUT_CUSTOM_URL_PREFIX``
     - *(empty)*
     - URL prefix prepended to all API requests. Useful when the API is hosted under a sub-path.
   * - ``SCALEOUT_PACKAGE_EXTRACT_DIR``
     - ``package``
     - Directory where the client extracts the downloaded compute package.
   * - ``SCALEOUT_GRACEFUL_GRPC_HANDLING``
     - ``true``
     - Whether the client handles gRPC disconnections gracefully and attempts reconnection (``true``/``false``).
   * - ``SCALEOUT_CHECK_COMPATIBILITY``
     - ``true``
     - Whether the client checks version compatibility with the server on connect (``true``/``false``).
   * - ``SCALEOUT_CLIENT_STATUS_REPORTING``
     - ``true``
     - Whether the client sends status updates to the server during commands (``true``/``false``).
   * - ``SCALEOUT_CLIENT_SEND_TELEMETRY``
     - ``true``
     - Whether the client sends telemetry data, CPU and memory usage (``true``/``false``).
   * - ``SCALEOUT_CLIENT_TASK_POLLING_INTERVAL``
     - ``5``
     - Interval in seconds between task polling requests from the client to the server. Lower values may reduce task start latency but increase API load.

Usage example
-------------

Set variables before starting the client:

.. only:: html

   .. tabs::

       .. code-tab:: bash
           :caption: Unix/MacOS

           export SCALEOUT_PACKAGE_EXTRACT_DIR=/tmp/package
           export SCALEOUT_CLIENT_TASK_POLLING_INTERVAL=10
           export SCALEOUT_CONNECT_API_SECURE=false
           export SCALEOUT_GRPC_SECURE=false
           scaleout client start --api-url <API_URL> --token <TOKEN>

       .. code-tab:: powershell
           :caption: Windows (PowerShell)

           $env:SCALEOUT_PACKAGE_EXTRACT_DIR="/tmp/package"
           $env:SCALEOUT_CLIENT_TASK_POLLING_INTERVAL="10"
           $env:SCALEOUT_CONNECT_API_SECURE="false"
           $env:SCALEOUT_GRPC_SECURE="false"
           scaleout client start --api-url <API_URL> --token <TOKEN>

       .. code-tab:: bat
           :caption: Windows (CMD)

           set SCALEOUT_PACKAGE_EXTRACT_DIR=/tmp/package
           set SCALEOUT_CLIENT_TASK_POLLING_INTERVAL=10
           set SCALEOUT_CONNECT_API_SECURE=false
           set SCALEOUT_GRPC_SECURE=false
           scaleout client start --api-url <API_URL> --token <TOKEN>

.. only:: latex or rinoh

   **Unix/MacOS:**

   .. code-block:: bash

      export SCALEOUT_PACKAGE_EXTRACT_DIR=/tmp/package
      export SCALEOUT_CLIENT_TASK_POLLING_INTERVAL=10
      export SCALEOUT_CONNECT_API_SECURE=false
      export SCALEOUT_GRPC_SECURE=false
      scaleout client start --api-url <API_URL> --token <TOKEN>

   **Windows (PowerShell):**

   .. code-block:: powershell

      $env:SCALEOUT_PACKAGE_EXTRACT_DIR="/tmp/package"
      $env:SCALEOUT_CLIENT_TASK_POLLING_INTERVAL="10"
      $env:SCALEOUT_CONNECT_API_SECURE="false"
      $env:SCALEOUT_GRPC_SECURE="false"
      scaleout client start --api-url <API_URL> --token <TOKEN>

   **Windows (CMD):**

   .. code-block:: bat

      set SCALEOUT_PACKAGE_EXTRACT_DIR=/tmp/package
      set SCALEOUT_CLIENT_TASK_POLLING_INTERVAL=10
      set SCALEOUT_CONNECT_API_SECURE=false
      set SCALEOUT_GRPC_SECURE=false
      scaleout client start --api-url <API_URL> --token <TOKEN>

.. note::
   Boolean variables accept ``true`` or ``false`` (case-insensitive).

.. seealso::
   :ref:`scaleout-cli` for the full list of ``scaleout client`` commands.

.. meta::
    :description lang=en:
        Reference for all environment variables supported by the Scaleout Edge Python client.
    :keywords: environment variables, client configuration, Scaleout Edge, federated learning