Network and security

Whale‑E only makes outbound HTTPS requests, used exclusively to download market data and check for updates. Outside of those two uses, the software does not initiate any other network communication. During update checks, the only additional value it may send is a pseudonymized client identifier (client_id), which you can disable.

Updates#

At startup, Whale‑E checks whether an update is available.

Update checks go through updates.whale-e.com. The requested URL depends on the installed version. For example, on Windows:

https://updates.whale-e.com/releases/whale-e/public/stable/windows-x86_64-msvc/update.json?client_id=<value>

The client_id parameter is a SHA-256 hash computed from local hardware metadata. It allows us to estimate the number of active users using an approximation based on unique machines. Raw hardware values are never sent.

If you do not want to send this identifier, you can disable it for a single run with --no-update-client-id. You can also disable it through the environment variable WHALEE_UPDATE_CLIENT_ID=0. The values 0, false, no, off, and disabled disable the identifier. The values 1, true, yes, on, and enabled enable it.

When a newer version is detected, it first validates the signed manifest. This cryptographic verification ensures that update metadata was not altered and comes from an authorized signing key.

The update is then checked against your binary, and the downloaded file is validated using its size and SHA-256 hash. Installation is performed only if every verification succeeds.

Domains to allow#

In direct mode, the software connects to these remote domains over HTTPS on port 443. When a proxy is configured, the network connection is opened to the proxy first, using its host and port, and access to these domains is then delegated to it.

The table therefore lists the remote hosts that must be reachable, either directly or through the proxy. This list matches the integrations currently supported.

TLS, proxy, and the network block#

Proxy settings and the [network] block belong to two different layers.

The proxy is a startup setting. It is read only from the environment variables inherited by the process. This makes the same proxy configuration available to history downloads and to updates, including cases where auto-update starts before the strategy file is fully loaded.

The [network] block is read from the strategy file and configures only the TLS policy used by requests executed after that strategy has been loaded. It exposes verify_tls, allow_insecure_tls, and ca_bundle_path. It does not configure the proxy.

For a detailed reference of this block, see Network.

If you need a custom CA bundle from process startup, especially for update checks, use the WHALEE_CA_BUNDLE environment variable. Once the strategy is loaded, WHALEE_CA_BUNDLE still takes precedence over [network].ca_bundle_path.

Here is an example of a network block.

[network]
verify_tls     = true
ca_bundle_path = "C:/certs/whale-e-ca-bundle.pem"

Proxy configuration#

If your network requires an HTTP proxy to reach the internet, the software can use it for outgoing requests. This covers update checks and downloads, and API calls used to download historical prices and market data from exchanges.

The proxy is not configured in the [network] block.

Proxy settings are read from environment variables inherited by the running process. These variables apply to requests to exchanges and to updates. For HTTPS requests, it checks these variables in this order: HTTPS_PROXY, https_proxy, HTTP_PROXY, then http_proxy. For HTTP requests, it checks these variables in this order: HTTP_PROXY, then http_proxy. For host exclusions, it reads NO_PROXY, then no_proxy.

Set the variable to host:port, http://host:port, or http://user:pass@host:port. Only HTTP Basic proxy authentication is supported. When authentication is used, the expected format is explicitly user:pass@host:port. A trailing empty slash after host:port is still tolerated, but do not append a path, query string, or fragment after host:port. If a proxy variable is set but invalid, an explicit error is reported and no silent fallback to a direct connection occurs.

When a proxy is configured, you can still force a direct connection for specific hosts. Set NO_PROXY to a comma-separated list.

Only hostnames are matched. Ports are ignored. Use * to bypass the proxy for everything, use an exact hostname such as updates.whale-e.com, or use a leading dot to match subdomains such as .whale-e.com. A leading dot matches subdomains, so .whale-e.com matches updates.whale-e.com but not whale-e.com. If the proxy interferes with exchange APIs, add the specific exchange hosts you need to bypass.

Windows (native)#

$proxy = "http://proxy.company.local:3128"
# $proxy = "http://user:pass@proxy.company.local:3128"

$env:HTTPS_PROXY = $proxy
setx HTTPS_PROXY $proxy

$env:HTTPS_PROXY only applies to the current PowerShell session. setx writes the value for new terminals, so you must close and reopen PowerShell to pick it up.

Windows system proxy settings are not read automatically.

setx NO_PROXY "updates.whale-e.com"

Linux Docker#

Proxy settings are read from environment variables. When you run the software in Docker, pass these variables to the container with docker run -e ...

proxy="http://proxy.company.local:3128"
# proxy="http://user:pass@proxy.company.local:3128"

docker run --rm -it \
  -e HTTPS_PROXY="$proxy" \
  -e NO_PROXY="updates.whale-e.com" \
  -v ~/whale-e-data:/data \
  whale-e