Proxy Configuration

Overview

Many secure networks require all outbound traffic to pass through a forward proxy, and block direct egress at the firewall. Agents built with istari-digital-client 13.0.0 or later honor the conventional proxy environment variables for all of their HTTP traffic, including the presigned object-store URLs used to transfer job files. On a host that already has its proxy configured in the environment, the agent works with no additional agent configuration — unless the proxy terminates TLS, in which case its CA certificate must also be trusted (see Proxies That Terminate TLS).

Proxy Environment Variables

The agent reads the standard variables, in upper or lower case (lowercase wins when both are set):

Variable	Purpose
HTTP_PROXY	Proxy for plain-HTTP destinations
HTTPS_PROXY	Proxy for HTTPS destinations
ALL_PROXY	Fallback when a scheme-specific variable is not set
NO_PROXY	Comma-separated hosts to reach directly, bypassing the proxy

NO_PROXY matches hosts exactly or as a dot-boundary suffix: NO_PROXY=internal.example bypasses the proxy for registry.internal.example but not for notinternal.example. A value of * bypasses the proxy entirely.

Proxy credentials may be embedded in the proxy URL (http://<user>:<password>@proxy.example:8080); they are sent as a Proxy-Authorization header and never written to logs.

On Windows, set these as system-level environment variables (for example with setx /M) so the agent process sees them regardless of how it is launched. setx only affects processes started afterwards, so restart the agent (or its Windows service) after changing them.

Control Plane over a Direct Route

When the Istari control plane is reached over a direct route — for example a site-to-site VPN — while the object store requires the proxy, list the control-plane host in NO_PROXY:

HTTPS_PROXY=http://proxy.example:8080
NO_PROXY=registry.customer.example

Registry API traffic then bypasses the proxy while file transfers ride it.

Proxies That Terminate TLS

There are two common proxy shapes:

• CONNECT tunneling — the proxy passes encrypted traffic through untouched. The proxy variables above are all that is needed.
• TLS termination — the proxy decrypts, inspects, and re-encrypts traffic with its own certificate authority. The agent must be told to trust that CA: point REQUESTS_CA_BUNDLE or SSL_CERT_FILE at a PEM bundle containing the proxy's CA certificate.

Certificate verification is always enforced; there is no option to disable it.

Explicit Settings

Explicit settings override the environment. Each is available as an environment variable or as an istari-digital-client Configuration argument:

Environment Variable	Purpose
ISTARI_CLIENT_PROXY_URL	Proxy for all HTTP(S) traffic; overrides HTTP_PROXY/HTTPS_PROXY/ALL_PROXY. NO_PROXY is still honored.
ISTARI_CLIENT_CA_BUNDLE	PEM CA bundle for TLS verification; overrides REQUESTS_CA_BUNDLE/SSL_CERT_FILE.
ISTARI_CLIENT_TRUST_ENV	Set to false to ignore all proxy and CA environment variables. The two explicit settings above still apply. Defaults to true.

SOCKS proxies are not supported: an explicit SOCKS ISTARI_CLIENT_PROXY_URL is rejected with an error, and a SOCKS URL arriving via environment variables is ignored with a warning — traffic connects directly rather than through the SOCKS proxy.

Verifying and Troubleshooting

• The first time the agent routes traffic through a proxy, it logs one line at INFO level: Using proxy http://proxy.example:8080 for outbound HTTP(S) traffic (NO_PROXY=...). If that line is absent while jobs fail to download, the proxy variables are not visible to the agent process.
• A connection timeout downloading job files, on a host where a browser or the AWS CLI can reach the same storage, usually means the agent is attempting direct egress: check that the proxy variables are set in the agent's environment.
• A certificate verification error immediately after enabling the proxy usually means the proxy terminates TLS: provide the CA bundle as described above.

Upgrading Hosts That Already Set Proxy Variables

Before istari-digital-client 13.0.0, proxy environment variables were ignored. A host that has them set but previously worked by connecting directly will start routing through that proxy after upgrading. If that is not intended, list the affected destinations in NO_PROXY, or set ISTARI_CLIENT_TRUST_ENV=false to restore the previous behavior.