http-proxy-agent 9.x

Complete instructions

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

http-proxy-agent 9.x

Runtime and module shape

• Version 9 is an ESM package and requires Node.js 20 or newer.
• Import the named HttpProxyAgent export:

import { HttpProxyAgent } from 'http-proxy-agent';

• Do not use CommonJS require() or assume a default export.
• The package implements an http.Agent for requests made through an HTTP or HTTPS proxy. For proxying via Node's https module, use https-proxy-agent instead.

Constructing an agent

The constructor is:

new HttpProxyAgent(proxy, options?)

proxy must be a proxy URL string or a URL instance. In v6 and later, pass it as the first argument and pass agent options separately as the second argument.

import { HttpProxyAgent } from 'http-proxy-agent';

const agent = new HttpProxyAgent(
  'https://proxy.example.test:8443',
  { keepAlive: true }
);

The proxy URL controls the proxy connection. An HTTPS proxy uses a TLS socket; an HTTP proxy uses a regular TCP socket.

The options accept normal Node http.Agent options and an additional headers option. headers can be either an object or a function returning an object:

import { HttpProxyAgent } from 'http-proxy-agent';

const agent = new HttpProxyAgent('http://proxy.example.test:3128', {
  keepAlive: true,
  headers: () => ({
    'X-Proxy-Request': 'example'
  })
});

Proxy headers can also reach the destination if the proxy does not strip them.

Inspecting the configured agent

The proxy URL is available as agent.proxy. Use its protocol to distinguish HTTP and HTTPS proxies; the old public secureProxy getter was removed in v7.

agent.proxyHeaders contains the configured header object or header-producing function. agent.connectOpts contains the connection options used for the proxy connection.

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

const headers = { 'X-Proxy-Request': 'example' };
const agent = new HttpProxyAgent('https://proxy.example.test:8443', {
  keepAlive: true,
  headers
});

assert.equal(agent.proxy.protocol, 'https:');
assert.equal(agent.proxy.hostname, 'proxy.example.test');
assert.equal(agent.proxy.port, '8443');
assert.deepEqual(agent.proxyHeaders, headers);
assert.equal(agent.connectOpts.host, 'proxy.example.test');
assert.equal(agent.connectOpts.port, 8443);

Supported protocols

The class advertises both HTTP and HTTPS request protocols through its static protocols property:

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

assert.deepEqual(HttpProxyAgent.protocols, ['http', 'https']);

const agent = new HttpProxyAgent(new URL('http://proxy.example.test:3128'));
assert.equal(agent.proxy.href, 'http://proxy.example.test:3128/');
assert.equal(agent.proxy.protocol, 'http:');

URL.href includes a trailing slash when the URL has no path, so compare against the normalized value with /.

Using the agent with Node HTTP

Pass the agent in the request options. The agent rewrites the request path to an absolute URL for the proxy, adds Proxy-Authorization: Basic ... when the proxy URL contains credentials, and uses Proxy-Connection: Keep-Alive when keepAlive is enabled; otherwise it defaults that header to close.

import * as http from 'http';
import { HttpProxyAgent } from 'http-proxy-agent';

const agent = new HttpProxyAgent('http://proxy.example.test:3128');

http.get('http://nodejs.org/api/', { agent }, (res) => {
  res.pipe(process.stdout);
});

This request requires a reachable proxy and destination. It is not suitable for an offline standalone example; exercise it in the application or integration environment that provides the proxy.

Public agent methods

The class exposes addRequest, setRequestProps, and connect, in addition to inherited http.Agent behavior. connect opens the proxy socket and therefore requires a real request context and reachable proxy; addRequest and setRequestProps operate on Node client-request objects. Do not call these methods with arbitrary plain objects merely to test them.

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

const agent = new HttpProxyAgent('http://proxy.example.test:3128');

assert.equal(typeof agent.addRequest, 'function');
assert.equal(typeof agent.setRequestProps, 'function');
assert.equal(typeof agent.connect, 'function');
assert.equal(typeof agent.createConnection, 'function');

Common version-migration mistakes

• Using the v5 constructor shape: v5 examples commonly pass one object shaped like deprecated url.parse() output, including protocol, host, port, auth, and timeout. Version 9 requires the proxy URL/string as argument one and options as argument two.
• Passing old parsed-URL fields: current examples use a URL string or URL instance. When representing proxy credentials in a URL-style object, current documented fields are hostname, port, username, and password, not the old host and auth combination.
• Reading secureProxy: that public getter was removed in v7. Check agent.proxy.protocol === 'https:' instead.
• Running on an older Node version: v9 requires Node.js 20 or newer.
• Expecting an HTTPS-module agent: this package is for HTTP requests through an HTTP/HTTPS proxy. Use https-proxy-agent when the request is made through Node's https module.

Not covered

This skill does not cover proxy-server setup, authentication-server behavior, network troubleshooting, TLS certificate configuration, the full Node http.Agent API, or integration-test setup. The request flow and the connect/request methods require a real reachable proxy and are only described here, not exercised by the offline examples.