Environment Variables
=====================

AGILab reads its configuration from environment variables. You can set them globally in
``$HOME/.agilab/.env`` or per-session before launching Streamlit / AGI installers. The table below
summarises the supported keys.

.. list-table:: Runtime configuration
   :header-rows: 1

   * - Variable
     - Default
     - Purpose
   * - ``APPS_DIR``
     - ``~/agilab/src/agilab/apps``
     - Root directory containing app projects; used when selecting the active app.
   * - ``APP_DEFAULT``
     - ``flight_project``
     - App loaded when no explicit project is provided.
   * - ``AGI_PYTHON_VERSION``
     - ``3.13``
     - Python version passed to ``uv`` when syncing or running apps.
   * - ``AGI_PYTHON_FREE_THREADED``
     - ``0``
     - Enables free-threaded Python if both the environment and worker declare support. Either the
       string ``"1"`` or a truthy value activates it.
   * - ``TABLE_MAX_ROWS``
     - ``1000``
     - Maximum number of rows shown in Streamlit data previews.
   * - ``TABLE_SAMPLING``
     - ``20``
     - Sample size used when previewing large tables.
   * - ``CLUSTER_CREDENTIALS``
     - Current OS user
     - Username/password pair (``user:pass``) used by cluster automation scripts.
   * - ``OPENAI_API_KEY``
     - unset
     - API key surfaced to features that rely on OpenAI endpoints.
   * - ``AGI_SHARE_DIR``
     - ``data``
     - Subdirectory under the AGILab home where shared datasets and outputs are stored.
   * - ``AGI_SCHEDULER_IP``
     - ``127.0.0.1``
     - Default scheduler host for distributed runs.
   * - ``AGI_LOG_DIR``
     - ``~/log``
     - Parent directory for install logs (``install_logs``), worker logs, and general telemetry.
   * - ``AGI_EXPORT_DIR``
     - ``~/export``
     - Target directory for exported artefacts.
   * - ``MLFLOW_TRACKING_DIR``
     - ``~/.mlflow``
     - Where MLflow tracking data is stored when experiments are enabled.
   * - ``AGI_PAGES_DIR``
     - ``agilab/apps-pages``
     - Location of Streamlit page bundles loaded by the Explore/Edit views.
   * - ``AGILAB_PRIVATE``
     - unset
     - Optional pointer to a private checkout containing apps or overrides.
   * - ``INSTALL_TYPE``
     - ``1``
     - Controls the installation mode passed to ``AgiEnv``/installers (1 = developer workflow).

Additional host specific keys are supported for worker provisioning (for example
``127.0.0.1_CMD_PREFIX`` or ``127.0.0.1_PYTHON_VERSION``); these are written automatically into
``$HOME/.agilab/.env`` when you run installers and rarely need manual editing.

Remember to restart the Streamlit session after changing ``$HOME/.agilab/.env`` so ``AgiEnv`` picks
up the new values.