.. _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_AUTH_REFRESH_TOKEN_URI``
     - *(unset)*
     - URI endpoint used to refresh the access token. If unset, token refresh is disabled.
   * - ``SCALEOUT_AUTH_REFRESH_TOKEN``
     - *(unset)*
     - Refresh token value used together with ``SCALEOUT_AUTH_REFRESH_TOKEN_URI``. If unset, token refresh is disabled.
   * - ``SCALEOUT_CONNECT_API_SECURE``
     - ``true``
     - Whether to connect to the API over TLS (``true``/``false``). Set to ``false`` for local non-TLS deployments.
   * - ``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:

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