Most of these are for unusual setups (containers, Kubernetes, service
managers). Day to day you only need HLE_API_KEY, and only if you would rather
not save the key with hle auth login.
The table is generated from the client, so every variable it reads is here. A
variable that is also a command-line flag is listed with that flag; the flag
wins when both are given.
Path of the agent token file to read instead of ~/.config/hle/agent.toml. hle daemon install agent sets it in the service so the service reads the file the token was enrolled into.
—
HLE_AGENT_TOKEN
Agent token (hle_...). Used when --token is not given; beats ~/.config/hle/agent.toml. Separate from the API key.
--token
HLE_API_KEY
API key for the relay. Used when --api-key is not given; beats the saved config file.
--api-key
HLE_CONFIG_DIR
Directory holding config.toml and agent.toml, instead of ~/.config/hle. Beats XDG_CONFIG_HOME.
—
XDG_CONFIG_HOME
When set, the client uses $XDG_CONFIG_HOME/hle for its config. An existing ~/.config/hle is still used if that directory does not exist yet.
true allows and false always refuses a remote update to an older version (also allow_downgrade in agent.toml). Unset follows the relay’s rollback flag.
—
HLE_HOME
Directory the agent’s self-update keeps its versions in (default ~/.local/share/hle).
—
HLE_INSTALL_METHOD
Declares how the client was installed, overriding detection: pipx, uv, venv, pip, brew, docker, ha-addon or kubernetes. Decides how hle update upgrades it.
—
HLE_IN_DOCKER
1, true or yes states that the client runs in a container, instead of leaving it to be inferred.
—
HLE_REMOTE_UPDATE
off (or remote_update = false in agent.toml) makes the agent refuse every update the dashboard requests. On by default.
—
HLE_UPDATE_HEALTH_TIMEOUT
Seconds an updated agent has to report healthy before it rolls back (default 90).
—
HLE_UPDATE_MANIFEST
Path of a JSON file mapping version to wheel sha256 (also update_manifest in agent.toml). When set, a remote update installs only a wheel whose digest it lists.
Bytes of streamed response chunks held in memory at once across all streams (default 8388608); a stream past it waits instead of failing.
—
HLE_HTTP_CHUNK_SIZE
Bytes read per chunk when streaming a response from the local service (default 262144).
—
HLE_SERVER_URL
HLE server the client talks to, for a test or self-hosted instance. Default https://hle.world; beats server_url in ~/.config/hle/config.toml. https:// only (http:// allowed for localhost).
—
SSL_CERT_DIR
Directory of CA certificates trusted when the client verifies a local service’s certificate (--verify-ssl).
—
SSL_CERT_FILE
CA bundle trusted when the client verifies a local service’s certificate (--verify-ssl), instead of the bundled set.
These are read by the relay server (hle_server), not the client. They matter
only if you self-host the relay; on hle.world the defaults are what runs.
Variable
Default
What it does
HLE_REQUEST_BODY_WARN_BYTES
268435456 (256 MiB)
A proxied request body at or above this size logs one Large request body WARNING per tunnel per minute, with a suppressed count. Measurement only — nothing is refused.
HLE_MAX_REQUEST_BODY
unset (off)
Maximum accepted proxied request body in bytes. Unset, empty or 0 disables the cap and every body is measured only. When set, an over-large Content-Length is answered 413 before the body is read, and a chunked body is counted and refused once it passes the cap. The 413 carries X-HLE-Error: request-too-large. Webhook tunnels keep their own 10 MiB limit regardless.
HLE_REQUEST_BODY_STALL_TIMEOUT
60
Seconds a streamed request body (client with the request_streaming capability) may go without progress — no bytes read from the browser, or no credit granted by the client — before the relay aborts it with an aborted HTTP_REQUEST_BODY_END and a HTTP_REQUEST_CANCEL. During the upload only this timeout applies; the response timeout starts once the body ends.
HLE_WAITING_WARN_TOTAL
2000
Relay-wide count of requests waiting on a tunnel client at or above which the sweep logs a WARNING and alerts ops (at most once per 15 minutes, plus one recovery line). 0 disables the relay-wide warning.
HLE_WAITING_WARN_TUNNEL
200
Same, per tunnel, naming its subdomain and zone. 0 disables the per-tunnel warning.
HLE_PUBLIC_MAX_RESPONSE_TIMEOUT
120
Response timeout (seconds) a public tunnel (auth_modenone, including webhook tunnels) is held to. A request’s effective timeout is min(tunnel timeout, this); private (SSO-gated) tunnels keep the full client-requested value.
HLE_RELAY_STREAM_IDLE_TIMEOUT
300
Seconds a started streamed response may go without a chunk before the relay cuts it. A text/event-stream response is never cut for silence (an idle SSE stream is normal, and cutting it just makes the browser’s EventSource reconnect), and 0 disables the limit for every started stream. Otherwise the limit is the larger of this and the tunnel’s response timeout, so a request timeout above it is never shortened. The time-to-first-response wait is unaffected.
Large request bodies (over 64 KiB) stream to the client end-to-end when the
client is the release from hle-client#268 or newer and advertised the
request_streaming capability, so an upload no longer sits whole in relay
memory. Older clients keep buffering the whole body, and webhook tunnels always
buffer it (signature checks need it).