Node.js HTTPS proxy setup

fetch with undici ProxyAgent

Node's fetch is built on undici. A ProxyAgent opens TLS to the proxy, sends CONNECT with your credentials, and then runs your HTTPS request inside the tunnel. Pass it as dispatcher on the calls that need a static IP.

// npm install undici  (undici 8 needs Node.js 22.19+)
import { fetch, ProxyAgent } from "undici";

// Create one agent and reuse it. It keeps connections to the proxy open.
const proxy = new ProxyAgent(process.env.FIXEDMARK_PROXY_URL);

const res = await fetch("https://api.partner.example/v1/orders", { dispatcher: proxy });
console.log(res.status, await res.json());

Importing fetch from the undici package keeps the agent and fetch on the same version. Passing an undici agent to the global fetch also works in our tests, but version mismatches between the two can break it.

Proxy from the environment

To proxy all requests, read HTTPS_PROXY and NO_PROXY. undici's EnvHttpProxyAgent does this for fetch. Node.js 22.21+ and 24.5+ can also do it with no packages for both fetch and the http and https modules.

// npm install undici
// HTTPS_PROXY=$FIXEDMARK_PROXY_URL
// NO_PROXY=localhost,127.0.0.1,.internal.example
import { EnvHttpProxyAgent, fetch, setGlobalDispatcher } from "undici";

// Every undici fetch now follows HTTPS_PROXY and NO_PROXY.
setGlobalDispatcher(new EnvHttpProxyAgent());

const res = await fetch("https://api.partner.example/v1/orders");
console.log(res.status);

# Node.js 22.21+ or 24.5+. Covers fetch and the http/https modules.
# Marked "Active Development" in the Node.js docs.
NODE_USE_ENV_PROXY=1 \
HTTPS_PROXY="$FIXEDMARK_PROXY_URL" \
NO_PROXY="localhost,127.0.0.1" \
node server.js

Proxying everything also sends calls to your own database APIs, logging, and telemetry through Fixedmark, and each one counts against your plan. List those hosts in NO_PROXY, or use a dedicated ProxyAgent for the allowlisted API only.

axios

axios has its own proxy option and also reads HTTPS_PROXY by default. Before version 1.16.1, it sent HTTPS requests to the proxy in full instead of opening a CONNECT tunnel, which does not work with Fixedmark. The reliable setup on any version is https-proxy-agent plus proxy: false.

// npm install axios https-proxy-agent
import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";

// https-proxy-agent opens TLS to an https:// proxy URL, then sends CONNECT.
const httpsAgent = new HttpsProxyAgent(process.env.FIXEDMARK_PROXY_URL);

const api = axios.create({
  httpsAgent,
  proxy: false, // stop axios from applying its own proxy logic or HTTPS_PROXY
  timeout: 15_000,
});

const res = await api.get("https://api.partner.example/v1/orders");
console.log(res.status, res.data);

Source: the axios v1.16.1 changelog lists a fix for HTTPS request data sent in clear text to an HTTP proxy (#10858). We confirmed 1.16.0 sends the full request and 1.16.1 uses CONNECT.

The https module and SDKs

Many SDKs do not use fetch. The Stripe and Salesforce Node SDKs, got, and the https module accept an agent or httpAgent option. Pass an HttpsProxyAgent. It supports https:// proxy URLs.

// npm install https-proxy-agent
import https from "node:https";
import { HttpsProxyAgent } from "https-proxy-agent";

const agent = new HttpsProxyAgent(process.env.FIXEDMARK_PROXY_URL);

https.get("https://api.partner.example/v1/orders", { agent }, (res) => {
  console.log(res.statusCode);
  res.resume();
});

SOCKS5

Use socks-proxy-agent when you want SOCKS5 for HTTP, or need a raw TCP connection from Node. Keep the socks5h:// scheme so the proxy resolves DNS. For databases, see databases.

// npm install socks-proxy-agent
// socks5h:// sends the host name to the proxy, so DNS resolves there.
import https from "node:https";
import { SocksProxyAgent } from "socks-proxy-agent";

const agent = new SocksProxyAgent(process.env.FIXEDMARK_SOCKS_URL);

https.get("https://api.partner.example/v1/orders", { agent }, (res) => {
  console.log(res.statusCode);
  res.resume();
});

Production tips

• Create the agent once at module scope. A new agent per request opens a new TLS session to the proxy every time and counts a new request.
• Set timeouts. A destination that drops packets from IPs it does not allow looks like a hang, not an error.
• On serverless platforms, the agent lives as long as the warm instance. That is fine. Cold starts open a new connection.
• Edge runtimes such as Cloudflare Workers and Vercel Edge have no proxy option for fetch. Run the call in a Node.js function instead.