Outbound proxy
Some models cannot be reached directly from servers in Russia. So that this does not become manual work for every operator, AiHummer issues the outbound proxy address during installation and decides by itself which route a request takes.
The short version
The proxy address comes from the vendor and lands in a private file on the server
— it is never stored in gateway.env and never reaches a log. If the proxy is
unset or unavailable, the request goes direct: the instance keeps working
instead of stalling.
What goes where
| Destination | Route |
|---|---|
| External model (foreign provider) | through the proxy, when it is configured and usable |
| The same model with the proxy unavailable | direct, with a warning in the log |
localhost, *.localhost, the instance’s own address |
always direct, bypassing the proxy |
That last row matters: an instance calling itself is never routed through the proxy, otherwise local calls would depend on an external channel.
The fallback: no proxy is not a refusal
Before 1.2.8 an unset or broken proxy meant a failed request. The behaviour is now different:
- proxy configured and usable → the request goes through it;
- proxy not configured → the request goes direct, and a warning is logged once with the reason “not configured”;
- proxy configured but the value is unusable → the request goes direct, with “configuration unusable” as the reason.
The warning is emitted once per start, not per request: otherwise it would flood the log and stop being read.
:::note The direct route is a fallback, not a replacement for the proxy. If a provider refuses requests from Russian addresses, a direct request to it will not succeed — but the refusal will come from the provider and will say so, instead of a generic “could not apply the setting”. :::
Where the address is stored
The value lives in a private file whose path is given by
AIHUMMER_OUTBOUND_PROXY_URL_FILE. The file must be:
- an absolute path;
- a regular file with permissions no wider than
0600; - at most 4096 bytes.
This is deliberate: the proxy address carries a password, so it must not sit in
gateway.env, which is read and copied during routine maintenance.
:::caution
The AIHUMMER_OUTBOUND_PROXY_URL variable, which holds the address as a direct
value, exists only for development builds. Release builds never read it — in
production only the file path is accepted.
:::
Which addresses are accepted
The same validation runs both when the setting is delivered and when it is used, so an unusable value is rejected immediately instead of turning later into “foreign models still blocked” with nothing in any log.
Accepted: scheme http or https, a non-empty host, no query string, no
fragment, no path (other than /).
🔴 A bare http proxy on a non-loopback host is refused on purpose. Over plain
http the Proxy-Authorization header travels in clear text on every single
connection, which would leak the proxy password continuously. Use https for a
non-local host.
How to see what is happening
# What is configured right now (the value is never printed — only whether it is set)
aihummer doctor
# Gateway log: the direct-route warning when the proxy was not applied
journalctl -u aihummer-gateway -n 200 | grep -i proxyA refusal to apply the setting names the reason — “not configured”, “configuration unusable” — instead of a generic “could not apply”. That is what separates “the address never arrived” from “the address arrived and is wrong”.
What the operator has to do
Usually nothing: the address is issued at install time. Two cases need attention.
- Your own proxy instead of the vendor’s. Put the address in a private file
with
0600permissions, pointAIHUMMER_OUTBOUND_PROXY_URL_FILEat it, and restart the gateway. - No proxy needed at all (the instance runs where models are reachable directly). Set nothing: an unset proxy means a direct request.