Skip to main content

Route platform traffic through a proxy

If your network only allows outbound HTTPS through a proxy, configure the Hosted Agent's built-in proxy support so its connection to the APIsec platform can transit it. The agent supports HTTP and SOCKS proxies, with optional authentication.

What the proxy covers​

Get the scope right before configuring — it is a common point of confusion:

  • The PROXY_* settings apply to the agent's outbound connection to the APIsec platform only — instruction polling, results, status, and error reporting.
  • Requests to your target APIs are never proxied. They always go direct from the agent to the target, regardless of proxy settings.
  • The agent does not read the host-level proxy environment variables HTTP_PROXY, HTTPS_PROXY, or NO_PROXY. Setting them has no effect on any agent traffic, and the agent logs nothing about them. The PROXY_* variables are the only proxy configuration the agent honors.

Prerequisites​

  • A proxy reachable from the Docker host that can pass HTTPS traffic to api.apisecapps.com (or your staged platform host) on port 443.
  • The proxy's type (HTTP or SOCKS), hostname, port, and credentials if it requires authentication.

Steps​

  1. Add the proxy variables to your generated install command:

    -e PROXY_MANAGER=true \
    -e PROXY_TYPE=HTTP \
    -e PROXY_HOST=proxy.internal.example.com \
    -e PROXY_PORT=3128

    For an authenticating proxy, also set:

    -e PROXY_USERNAME=<username> \
    -e PROXY_PASSWORD=<password>

  2. Run the container.

When PROXY_MANAGER=true, the agent requires a valid PROXY_TYPE (HTTP or SOCKS) and a PROXY_PORT greater than 0. If either is invalid, the agent fails to start with the error Invalid proxy configuration. Under the install command's --restart=unless-stopped policy, a container that fails at startup restart-loops — read the error with docker logs.

An empty or unreachable PROXY_HOST is not caught at startup. The agent starts normally and then fails to reach the platform, so check the host value if an agent starts but never becomes ACTIVE.

note

The install script's own reachability check is a direct TCP connection from the host to the platform on port 443 — it does not use the agent's proxy settings, and the script stops if the check fails. Only the agent container's platform traffic transits the proxy.

Verify​

  • The agent shows ACTIVE in Manage Hosted Agents — its heartbeats are reaching the platform through the proxy.
  • The container logs show no platform connection errors.

If the agent stays PROVISIONED, confirm the proxy itself can reach the platform host on 443, then work through Troubleshooting.