Documentation gap: WITH_PROXY is a boolean toggle, not a proxy address — needs clear configuration guide

[DeniseMonreale]

Problem

There is a recurring point of confusion in community/support channels (3+ separate threads in the last 2 weeks) around configuring a proxy for the OpenAEV agent. Users assume the WITH_PROXY parameter accepts or requires a proxy address, when in fact it is a boolean toggle only.

Confirmed current behavior (from code)

WITH_PROXY is a bool that flows unchanged through the entire install chain:

• Command builder (Java, OpenaevImplantCommandBuilder.java): --with-proxy $with_proxy
• Installer scripts (PowerShell agent-installer.ps1 / bash): ~WITH_PROXY=${OPENAEV_WITH_PROXY}
• Rust agent client (src/api/mod.rs):

  if !with_proxy {
      http_client = http_client.no_proxy();
  }

When WITH_PROXY=true, the agent's HTTP client (reqwest) simply does not disable proxy detection, meaning it falls back to reading the system-level environment variables HTTP_PROXY / HTTPS_PROXY. There is currently no parameter to pass an explicit proxy address through OpenAEV's own configuration (tracked separately as a feature request).

What's missing from documentation

1. No clear explanation that WITH_PROXY=true requires HTTP_PROXY/HTTPS_PROXY to be already set at the OS/environment level before the agent starts — the flag itself does not configure a proxy, it only tells the agent whether to respect the system proxy settings or ignore them (no_proxy()).
2. No documented example showing the full expected configuration (e.g. setting HTTP_PROXY/HTTPS_PROXY env vars on Windows via setx or Group Policy, and on Linux via /etc/environment or systemd service env, combined with WITH_PROXY=true at install time).
3. No mention of interaction with authenticated proxies (proxy requiring username/password) — unclear whether this is supported at all via the env var fallback, and not documented either way.
4. No documentation on Defender / EDR signature exclusions for the agent binary/process — this has also come up in the same community threads as a related but separate pain point when agents are deployed behind corporate proxies/EDR and get blocked or flagged.

Use case

A user deploying the OpenAEV agent behind a corporate proxy sets WITH_PROXY=true expecting it to "just work" or expecting a place to type the proxy address, gets no clear result, and has no documentation to explain that the actual proxy configuration must happen at the OS environment level first. This generates repeated, avoidable support load (3 separate Slack threads in 2 weeks on the same root confusion).

Proposed fix

Add a dedicated documentation page / README section covering:

• What WITH_PROXY does and does not do (boolean toggle vs. actual proxy configuration)
• Step-by-step example: setting HTTP_PROXY/HTTPS_PROXY at OS level (Windows + Linux) and then installing the agent with WITH_PROXY=true
• Whether authenticated proxies are supported today, and if not, state it explicitly
• Guidance on Defender/EDR signature/process exclusions needed for the agent to run reliably behind a corporate proxy/security stack

Related

• Feature request tracked separately: adding an explicit PROXY_ADDRESS configuration option (see companion issue in this repo).