Environment Variables

This page lists every HORUS_* variable that shipped, non-test code reads, and every one HORUS sets for a process it starts — a node under horus launch, a Python node under horus run, an exec driver, a CLI plugin. The ones you would set deliberately come first, grouped by area; the internal and test-only ones are at the bottom so you can recognise one if you see one.

There is deliberately no count in this sentence. The version of this page that carried one opened with "HORUS reads 47 HORUS_* variables" while its own tables listed 43 distinct names.

What this page does not cover

The integration-test tree carries its own environment surface — names of the shape HORUS_<SUITE>_CHILD, _TOPIC, _ROLE, _COUNT, whose entire job is to let a test coordinate with a process it spawns. They outnumber the real ones: of the 199 distinct HORUS_* string literals in the repository outside target/, 94 appear somewhere under a src/ directory and 105 appear only in test files. None of those 105 is reachable from an installed HORUS, none has a default worth knowing, and listing them would bury the page. They are not here, and horus_manager/tests/docs_parity.rs:150-154 records the same reason for keeping them out of the check that guards it.

Two automated checks stand behind the rest, and it is worth knowing what each one can and cannot see. Both run in the contract-live job of .github/workflows/docs-contract.yml, on every pull request, against a pinned horus-docs commit.

docs_contract::every_environment_variable_is_in_the_reference_page builds a surface from four scans and fails when a name in it is absent from this page:

• Rust files under a src/ path, where the name is a literal directly inside env::var(, env::var_os(, env::set_var(, .env( or env.insert( — matches inside a #[cfg(test)] module are dropped;
• .cpp, .cc, .hpp and .h outside tests/, for getenv( and secure_getenv(;
• .py outside tests/, for os.environ.get(, os.environ[ and os.getenv(;
• install.sh and uninstall.sh, for any $HORUS_* the script references and never assigns.

The first scan is the one doing the work. The C++ and Python scans match nothing in this repository today — no shipped .cpp or .hpp calls getenv at all, and no shipped .py file names a HORUS_* variable — and the non-vacuity guard at docs_contract.rs:908-926 probes only three of the four, so if either of them ever did match and then stopped, nothing would say so.

Inside the Rust scan, four shapes are invisible, and all four are in use:

• a read through a helper — csv_env("HORUS_NET_EXPORT_STREAM") at horus_net/src/config.rs:257;
• a read through a constant — env::var(LEVEL_ENV) at horus_core/src/core/hlog.rs:123, where LEVEL_ENV is HORUS_LOG_LEVEL. HORUS_NO_PROXY_NOTICE and HORUS_SHELL_PROXY reach the code the same way, through the constants at horus_manager/src/commands/proxy.rs:47 and :55;
• a name built at runtime — format!("HORUS_REAL_{}", tool_name.to_uppercase()) at horus_manager/src/commands/proxy.rs:417;
• a read in generated code — HORUS_MSGS_FFI and HORUS_MSGS_FFI_BUILD are read by Python that lives inside a Rust string literal (horus_manager/src/msgspec/emit_python.rs:140 and :180), which the Rust scan does not parse and the Python scan never opens.

HORUS_NET_EXPORT_STREAM went undocumented behind exactly the first of those. If you add a variable through a helper, a constant, a format! or a generated file, no check will remind you; add it here by hand.

The second check, docs_manifest::documented_env_vars_are_read, runs the other way: a HORUS_* name written on any documentation page must appear somewhere in shipped source — every .rs, .toml, .sh, .h, .hpp, .hh, .cpp, .cc, .py and .yml file outside target/ and outside every directory named tests. A variable invented in prose therefore fails the build. Three things soften it, and this page depends on all three:

• a heading containing internal or test-only exempts the section under it, which is why a genuinely test-only variable has to live in the last section here rather than in a table above;
• a line that disclaims a variable — "nothing reads", "there is no", "does not" — is skipped, which is what lets the Set but not read table below name variables and then say nothing reads them;
• a name matching a prefix the source builds at runtime is accepted, so HORUS_PARAM_MAX_SPEED is covered by the format!("HORUS_PARAM_{}", …) in commands/launch.rs and HORUS_REAL_CARGO by the one in commands/proxy.rs.

It matches on the name appearing, not on a read, so it catches invention rather than staleness.

Variables that relax a check

Every one of these has a safe default and a reason someone turns it off. They are collected here so an operator hardening a deployment has one list to audit; each also appears in its subsystem's table below with the full detail.

HORUS_ESTOP_KEY is the opposite case: it is the only variable here that adds a check, and until it is set every remote emergency stop is rejected.

Logging

The error buffer is separate on purpose: a node logging at high rate can evict its own errors from the main buffer. horus log --level warn and --level error read the error ring instead of the main one, which is the longer retention (horus_manager/src/commands/log.rs:201-206); anything below warn reads the main ring. Logs replicated from peers are merged into the same output from a third buffer.

HORUS_LOG_LEVEL is read once per process and latched, on the first hlog!. The filter lives in the macro so a suppressed line never evaluates its arguments. There is no HORUS_LOG; nothing reads that name.

Networking

Only meaningful with the net capability enabled — see Configuration.

WSL2 is detected by looking for microsoft in /proc/version, because its virtualised network adapter adds tens to hundreds of milliseconds of UDP jitter and the native timings produce false link-lost reports.

HORUS_NET_EXPORT_STREAM, and the 20 Hz you did not ask for

Outbound replication is driven from the replicator's timer, which fires every 50 ms (horus_net/src/replicator.rs:44). The default export takes the newest sample on each tick and leaves the rest, so every replicated topic crosses the network at roughly 20 Hz however fast its publisher runs. That is correct for state — a pose, a battery level — and wrong for a measurement stream, where the receiver integrates every sample. A 500 Hz odometry stream crossed the LAN at 20 Hz and looked, at the far end, exactly like a 20 Hz odometry stream, and nothing counted or said so (horus_net/src/replicator.rs:904-926).

List the streaming topics and every message crosses:

HORUS_NET_EXPORT_STREAM='odom,joint_states,lidar.*' horus run

A streaming topic contributes at most 64 messages to one export tick (MAX_EXPORT_BATCH, replicator.rs:57); the reader resumes from its own cursor, so the remainder goes out on the next tick rather than being dropped. At the 50 ms timer that is 1280 messages per second per topic sustained.

Whatever a topic is set to, what it drops is now counted and reported; the warning that names the drops also names this variable (horus_net/src/shm_reader.rs:140).

This is the one networking variable with no horus.toml equivalent. The [network] table has fields enabled, import, deny_export, secret, optimize and safety and no export_stream (horus_manager/src/manifest.rs:276-303), and the per-topic export_sampling override that would express the same thing (horus_net/src/config.rs:217) lives in a map that nothing outside the two test suites ever populates (horus_net/src/config.rs:44, :261). The environment variable is the only route there is.

How [network] in horus.toml reaches the runtime

horus run translates the [network] table into these variables for the child process, in horus_manager/src/commands/run/mod.rs:79-142: HORUS_NO_NETWORK, HORUS_NET_SECRET, HORUS_NET_DENY_EXPORT, HORUS_NET_OPTIMIZERS, HORUS_NET_IMPORT, HORUS_NET_HEARTBEAT_MS, HORUS_NET_MISSED_THRESHOLD and HORUS_NET_ON_LINK_LOST. A variable already set in your environment wins — an explicit HORUS_NET_*=… on the command line is never overridden by a project file.

Two consequences worth knowing before you rely on the manifest. The translation runs on one path only, execute_multiple_files, which is reached when horus run is given more than one file or a glob that matches more than one (mod.rs:236-238 and :834); a single file, a directory and a horus.toml run get none of it. And horus launch performs no such translation at all — horus_manager/src/commands/launch.rs sets no HORUS_NET_* name. Where the manifest route does not reach, the environment variable does.

Safety

Note the default on HORUS_ESTOP_REMOTE: an unrecognised value warns rather than disabling, so a typo cannot silently switch off remote e-stop. The key is read once per process and cached, so the KDF cost is paid at first use and never on the packet path. The salt is fixed and domain-separated; there is nowhere to put a per-deployment one when both ends must derive the same bytes from a bare environment variable.

Runtime

Parameters

HORUS_PARAM_<NAME> sets the runtime parameter <name>, lowercased:

HORUS_PARAM_MAX_SPEED=2.5 HORUS_PARAM_DEBUG=true horus run

reaches your node as self.params.get::<f64>("max_speed") and get::<bool>("debug").

This is the highest-precedence layer: it beats .horus/config/params.yaml, which beats the built-in defaults. Each layer overrides individual keys of the one below it rather than replacing the whole map — before that was true, a single HORUS_PARAM_CAMERA_FPS=60 from a launch file suppressed the entire built-in set, including emergency_stop_distance and max_speed.

horus launch and the exec driver both build these names from your parameter keys, uppercasing them; horus launch also replaces - with _, so a launch key max-speed arrives as HORUS_PARAM_MAX_SPEED. The exec driver does not, so a driver parameter with a hyphen in its key produces a name a shell cannot export. A variable set by hand overrides a launch file for that run.

CLI and toolchain

HORUS_NET on its own does not build a networked binary, and neither does the capability list on its own. horus run --net sets HORUS_NET=1 and appends net to the capability list, which is written to HORUS_ENABLE (main.rs:2534-2542). The net capability deliberately contributes no Cargo feature to your own crate — enable_to_features returns an empty list for it, because your crate has no such feature and passing it produces "the package does not contain this feature: net". What turns it on is cargo_gen, which reads HORUS_ENABLE (or the top-level enable = [...] key in horus.toml) itself and adds net to the horus dependency in the generated manifest (horus_manager/src/cargo_gen.rs:1025-1037).

Installer

Read by install.sh and by install.ps1, which takes the same six names.

HORUS_PREFIX is read by the CLI as well as by the installer, and in two places. horus run searches $HORUS_PREFIX/cache for the installer-cached horus@<version> tree before ~/.cache/horus and ~/.horus/cache (horus_manager/src/commands/run/run_rust.rs:1023-1042), so a prefix install can build a single Rust file without you exporting HORUS_SOURCE by hand. And the version gate resolves its state root from the same variable (horus_manager/src/version.rs:63-76, :106-112), so installed_version and install_manifest.toml are read from under the prefix.

install.sh has not caught up with either. A prefix install still ends by telling you to export HORUS_SOURCE=… and by saying "the version gate is inactive for a prefix install: version.rs looks in ~/.horus" (install.sh:1108-1126). Neither statement is true of the Rust code cited above. Follow the code, not the epilogue.

These are read from the installer's environment, so with a pipe they belong on the right-hand side — HORUS_VERSION=v0.4.0 curl ... | bash puts the variable in curl's environment, where nothing reads it:

curl -fsSL https://github.com/softmata/horus/raw/main/install.sh | HORUS_VERSION=v0.4.0 bash

PowerShell has no VAR=value command prefix form at all, so there they are set as their own statement first:

$env:HORUS_VERSION = 'v0.4.0'
irm https://github.com/softmata/horus/raw/main/install.ps1 | iex

env -u HORUS_VERSION sh -c 'curl -fsSL https://github.com/softmata/horus/raw/main/install.sh | bash'

Set by HORUS for the processes it starts

You do not set these; HORUS puts them into the environment of a process it spawns, so they are readable from your node, driver or plugin. They are listed because they are a contract: your code may read them, and a release that renamed one would break that code.

horus run additionally injects the eight networking names listed under the manifest translation. The CLI sets HORUS_DRIVERS and HORUS_ENABLE in its own process environment from --drivers/--enable on horus run, horus build and horus test; HORUS_RECORD_SESSION from horus run --record; HORUS_NET from --net; HORUS_SIM_MODE and HORUS_SIM_TARGETS from --sim; and HORUS_ASSUME_YES from horus new --yes. A child inherits all of them.

Set but not read

These are put into a child's environment and nothing in HORUS reads them back. They are documented rather than hidden because they are visible to your code and because their emptiness is the answer to "why did setting this in my launch file do nothing?".

Internal and test-only

Set by HORUS itself or by its own test suite. Listed so you can recognise them, not so you can set them. Nothing here is reachable from an installed HORUS.

The first four are read by the CI test node in src/bin/, which is shipped code by path but exists only to be driven by the introspection contract tests. HORUS_CI_BEST_EFFORT and HORUS_CI_TOPIC_IN_CTOR shape the two arrangements that report their metrics through different mechanisms and have failed independently of each other, which is why both exist.

The integration-test tree carries around a hundred further names of the same kind — a test, the process it spawns, and the topic or role they agree on. They are excluded on purpose, both from this page and from the check that guards it.

(HORUS_INSTALL_BRANCH used to be listed here. It is set by the person running install.sh, not by HORUS, so it belongs in the installer table above.)

There is no HORUS_LOG and no HORUS_API_KEY: the first is spelled HORUS_LOG_LEVEL, and the registry key is read from auth.json and nowhere else.