proxy-agent 8.x

Complete instructions

Verified against proxy-agent@8.0.2 on 2026-09-08. 3 of 3 examples executed.

proxy-agent 8.x

Runtime and module requirements

• ^8.0.0 currently resolves to the 8.x line; the latest listed release is 8.0.2.
• Node.js 20 or newer is required. Version 8 raised the minimum Node.js version to 20.
• The package is ESM. Import its runtime exports with import; do not use the older CommonJS shape.
• The documented runtime exports are ProxyAgent and proxies. ProxyAgentOptions is a TypeScript type export.
• There is no documented CLI. Use the programmatic API or pass the resulting agent to Node's HTTP client.

Default environment-based proxying

Construct ProxyAgent with no options to select an underlying agent from the request URL and the usual http_proxy, https_proxy, no_proxy, and related environment variables. If no proxy is configured for a request, it creates or uses default http.Agent/https.Agent instances.

import assert from 'node:assert/strict';
import { ProxyAgent } from 'proxy-agent';

const agent = new ProxyAgent();
assert.equal(typeof agent.connect, 'function');
assert.equal(typeof agent.destroy, 'function');
agent.destroy();

Use it as the agent option in Node's normal HTTP or HTTPS APIs. For example, pass it as { agent } to https.get(...); the request otherwise works like a normal Node HTTPS request. A real request requires a reachable destination and is therefore not used as a standalone example here.

Selecting a proxy programmatically

Pass getProxyForUrl when proxy selection must be controlled by application code. Its callback receives (url, req) and may return a string synchronously or asynchronously. Return an empty string when the request should bypass a proxy.

import assert from 'node:assert/strict';
import { ProxyAgent } from 'proxy-agent';

let calls = 0;
const agent = new ProxyAgent({
  getProxyForUrl: async (url, req) => {
    calls++;
    assert.equal(typeof url, 'string');
    assert.ok(req);
    return url.startsWith('https:')
      ? 'http://proxy-server-over-tcp.com:3128'
      : '';
  },
});

assert.equal(typeof agent.connect, 'function');
assert.equal(calls, 0); // selection is made when a request is connected
agent.destroy();

The callback is evaluated during request handling, not when the ProxyAgent is constructed. A proxy URL must identify a supported proxy protocol such as HTTP(S), SOCKS, or PAC; low-level behavior is delegated to the corresponding proxy-agent dependencies.

Exported lazy agent constructors

proxies maps proxy protocols to lazy constructors. Each supported protocol entry is a two-element array: [forHttpRequests, forHttpsRequests]. Documented keys include:

• http
• https
• socks
• socks4
• socks4a
• socks5
• socks5h
• pac+data
• pac+file
• pac+ftp
• pac+http
• pac+https

These constructors can be used when integrating lower-level agents directly. The returned values are lazy-constructor results; do not assume they are Node agents with an instance .destroy() method.

import assert from 'node:assert/strict';
import { proxies } from 'proxy-agent';

assert.ok(proxies.http);
assert.equal(proxies.http.length, 2);
assert.equal(typeof proxies.http[0], 'function');
assert.equal(typeof proxies.http[1], 'function');

const httpAgent = await proxies.http[0]();
const httpsAgent = await proxies.http[1]();
assert.ok(httpAgent);
assert.ok(httpsAgent);

PAC support is delegated to pac-proxy-agent; SOCKS support is delegated to the corresponding SOCKS proxy-agent implementation. Do not assume all protocol-specific behavior is implemented in this package itself.

Lifecycle and custom agents

ProxyAgent exposes:

• connect(req, opts): Promise<http.Agent> for selecting or resolving the underlying agent during a request.
• destroy(): void for releasing the proxy agent and its cached underlying agents.

The proxy agent uses an LRU cache for proxy agents. Call destroy() when the owning client is finished, especially for long-lived applications or when replacing an agent.

ProxyAgentOptions also supports custom httpAgent and httpsAgent values, allowing callers to provide fallback agents for the corresponding request types. The documented construction shape is new ProxyAgent({ httpAgent, httpsAgent }); destroy the resulting ProxyAgent when it is no longer needed.

Common version and shape mistakes

• Do not target Node versions below 20: v8 explicitly raised the minimum.
• Do not copy a CommonJS import shape from older examples. v7 had already moved the packages to ESM; v8's major compatibility change is primarily the Node floor, but the published package is still consumed through its ESM export.
• Do not expect a CLI, describe, it, or runner-provided globals. This package exposes agents and helpers, not a test or command runner.
• Do not treat ProxyAgent as a fixed HTTP proxy agent. It chooses an underlying agent per request based on the URL, callback, and proxy environment.
• Do not omit agent.destroy() when the ProxyAgent is no longer needed.
• Do not call .destroy() on values returned by proxies lazy constructors unless their actual returned shape provides that method; the documented surface only establishes that they are lazy constructors.
• Do not assume undocumented deep imports are available. The published export surface is the package entry point, with runtime exports ProxyAgent and proxies.

Not covered

This skill does not cover detailed proxy URL authentication, exact no_proxy matching rules, PAC file contents or evaluation semantics, SOCKS protocol options, the complete http.Agent/https.Agent option set, or behavior of the delegated low-level agent packages. It also does not cover network-dependent request results or package-maintainer build, test, lint, and packaging commands.