.. _heros-conf:

Configuring HEROS
#################

Besides the config mechanisms through the :external:ref:`BOSS <json-head>` starter and :ref:`event decorators <sec-events>`,
HEROS is configured through environment variables.
Subprocesses, such as atomiq workers and BOSS, inherit them.

An empty variable counts as unset.
An invalid value raises a ``ValueError`` that names the variable.

``HEROS_DISCOVER_TIMEOUT`` is read each time a HERO or observer is created, ``HEROS_LOG`` when a logger is created.
All other variables are read when the first HERO of a realm opens its zenoh session in a process.
That session is reused until every HERO of the realm is closed, so later changes do not apply to it.

.. rubric:: Environment variables

**HEROS_LOG**
  Set the log level of all HEROS related systems.

**HEROS_DISCOVER_TIMEOUT** :bdg-info:`>2026.4.1`
  Time in seconds that HEROs and observers wait for answers to discovery queries, for example ``HEROS_DISCOVER_TIMEOUT=5``.
  Must be a finite number larger than 0.
  Default: :py:data:`heros.heros.DEFAULT_DISCOVER_TIMEOUT` (2 s).

  .. note::

    The timeout is meant for network latency.
    It does not wait for HEROs that are not started yet, so keep retrying for those.
    It also applies to HEROs that are :ref:`created inside zenoh callbacks <sec-nested-callbacks>`, so a long value can block those callbacks.

**HEROS_SEP_MULTICAST** :bdg-info:`>0.10.0`
  If true, different realms use different multicast addresses for discovery.
  This means the HEROS of different realms will not discover each other and can not communicate.
  The ``heros`` realm always uses the standard zenoh address.
  Accepted values are ``1``, ``true``, ``yes``, ``on`` and ``0``, ``false``, ``no``, ``off``, case-insensitive.
  In code, ``ZenohSessionManager(sep_multicast=True)`` or ``False`` overrides the variable.
  Default: true :bdg-info:`>2026.4.0`.

  .. note::

    You can get the multicast group for your realm by running
    ``uv run python -c "import heros; print(heros.helper.generate_multicast_address('my_realm'))"``

  .. note::

    If you want to run a `zenohd` router, you need to run it on the correct multicast group for your realm for example by
    ``zenohd --cfg='scouting/multicast/address:"<multicast-group-ip>:7446"'``

**HEROS_ZENOH_MODE** :bdg-info:`>2026.4.1`
  The zenoh mode: ``peer``, ``client`` or ``router``.
  Use ``client`` together with ``HEROS_ZENOH_CONNECT`` when multicast discovery cannot reach the other HEROs,
  for example from a Docker container or another subnet.
  Default: the mode from ``HEROS_ZENOH_CONFIG``, otherwise zenoh's default (``peer``).

**HEROS_ZENOH_CONNECT** :bdg-info:`>2026.4.1`
  Comma-separated zenoh endpoints to connect to, for example ``HEROS_ZENOH_CONNECT=tcp/172.16.50.2:7447,tcp/router:7447``.
  Replaces any endpoints set in ``HEROS_ZENOH_CONFIG``.
  Default: the endpoints from ``HEROS_ZENOH_CONFIG``, otherwise none.

**HEROS_ZENOH_CONFIG** :bdg-info:`>0.12.0`
  Can be used to alter the configuration of the Zenoh process. Must be supplied in the form of a valid json configuration string as described
  in the `example <https://github.com/eclipse-zenoh/zenoh/blob/main/DEFAULT_CONFIG.json5>`_. For example ``HEROS_ZENOH_CONFIG='{"queries_default_timeout": 30000}'``.
  Use ``HEROS_ZENOH_MODE`` and ``HEROS_ZENOH_CONNECT`` for mode and endpoints, and this variable for everything else.
  If a setting is given in several places, the later one wins: ``HEROS_ZENOH_CONFIG``, then ``HEROS_SEP_MULTICAST``,
  then ``HEROS_ZENOH_MODE`` and ``HEROS_ZENOH_CONNECT``, then :py:meth:`~heros.zenoh.ZenohSessionManager.update_config` in code.

  .. warning::

    This can have negative side effects if configurations are incompatible with the default HEROS settings and should be considered a last resort option.

.. rubric:: Example: connect a container to a router

When multicast does not reach the other HEROs, connect to a zenohd router instead:

.. code-block:: yaml

   environment:
     HEROS_ZENOH_MODE: client
     HEROS_ZENOH_CONNECT: tcp/<IP_OR_HOSTNAME>:7447

.. _sec-query-timeout:

.. rubric:: Query timeout

Method calls, attribute access and the capabilities query wait up to zenoh's ``queries_default_timeout`` (milliseconds).
Set it through ``HEROS_ZENOH_CONFIG`` as in the example above.
Discovery uses ``HEROS_DISCOVER_TIMEOUT`` instead.