Configuring HEROS

Besides the config mechanisms through the BOSS starter and event decorators, 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.

Environment variables

HEROS_LOG

Set the log level of all HEROS related systems.

HEROS_DISCOVER_TIMEOUT >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: 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 created inside zenoh callbacks, so a long value can block those callbacks.

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

Example: connect a container to a router

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

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

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.