Setup a Static IP for Node.js using https-proxy-agent

Give selected Node.js HTTPS requests a managed static outbound identity with QuotaGuard. Keep the proxy URL in your runtime secrets, explicitly configure the client making the request, and let QuotaGuard operate the proxy infrastructure, monitoring, maintenance, and failover.

Prerequisites

Use Node.js 24 and the ES module example below, saved as https.mjs. The package version is explicit so the installation and import agree:

npm init -y
npm install --save-exact https-proxy-agent@9.1.0

In an existing project, skip npm init and install the dependency there. Commit the resulting package manifest and lockfile, not your credentials. The .mjs extension selects ES modules without changing the module type of the rest of your application. Keep dependencies and the Node runtime updated through your normal maintenance process.

Instructions

Configure the runtime secret

Set QUOTAGUARDSTATIC_URL through your deployment platform's server-side secret configuration. Use the complete connection URL from the QuotaGuard dashboard:

http://username:password@<your-quotaguard-proxy-host>:9293

This is a format example, not a real hostname or credential. Do not print the URL, commit it, put it in a Dockerfile, or share it in screenshots. Once the secret is present in the process environment, run:

node https.mjs

An environment variable stores the connection setting. It does not route traffic until the HTTP client uses it.

Run in Docker

With QUOTAGUARDSTATIC_URL already supplied to your shell securely:

docker build -t qg-static-node-https-example .
docker run --rm --env QUOTAGUARDSTATIC_URL qg-static-node-https-example

The secret is supplied when the container runs, not baked into an image layer. This example does not require copying a .env file into the image.

Using fetch instead?

HttpsProxyAgent is for clients that accept a Node HTTP agent, including node:https and the separately imported node-fetch package. Node's built-in fetch uses Undici and a compatible dispatcher, not this agent option. Do not copy { agent } into an unqualified native fetch() call and assume it uses the proxy. See Node's dispatcher documentation.

Managed identity and security

QuotaGuard Static starts at $19 per month and supplies a stable pair on shared infrastructure. Choose Enterprise dedicated infrastructure when the destination requires addresses used only by your organization. Keep application authentication, authorization, and HTTPS with either option.

For outbound HTTPS, QuotaGuard Static does not decrypt the application payload. Its customer-to-proxy CONNECT and proxy authentication use unencrypted HTTP proxy protocol. Shield starts at $29 per month and adds TLS on that hop; use the Shield connection configuration with a compatible client when your security review requires it. See data flow and current plans.

Choose from 12 AWS regions at signup; contact support for a region change. QuotaGuard operates the managed exit, so your team does not have to maintain a proxy VM simply to preserve a client's allowlist.

Code Samples

https.mjs

import https from 'node:https';
import { isIP } from 'node:net';
import { HttpsProxyAgent } from 'https-proxy-agent';

async function main() {
  const proxyUrl = process.env.QUOTAGUARDSTATIC_URL;
  if (!proxyUrl) throw new Error('QUOTAGUARDSTATIC_URL is required');

  const agent = new HttpsProxyAgent(proxyUrl);
  try {
    const body = await new Promise((resolve, reject) => {
      const req = https.get('https://ip.quotaguard.com', {
        agent,
        signal: AbortSignal.timeout(15000),
      }, (res) => {
        res.on('error', reject);
        if (res.statusCode !== 200) {
          res.resume();
          reject(new Error('IP check returned an unexpected status'));
          return;
        }
        let body = '';
        res.setEncoding('utf8');
        res.on('data', (chunk) => {
          body += chunk;
          if (body.length > 4096) req.destroy(new Error('IP response too large'));
        });
        res.on('end', () => resolve(body));
      });
      req.on('error', reject);
    });

    const { ip } = JSON.parse(body);
    if (typeof ip !== 'string' || !isIP(ip)) {
      throw new Error('IP check did not return an address');
    }
    console.log(`Observed outbound IP: ${ip}`);
  } finally {
    agent.destroy();
  }
}

main().catch(() => {
  console.error('IP check failed. Check the proxy secret, network access, and account configuration.');
  process.exitCode = 1;
});

Compare the returned address with the pair in your QuotaGuard dashboard and allowlist both at the destination. A request may use either address; a short test does not have to display both. The check proves this request's route, not that every process or SDK in the application is using QuotaGuard.

The sample intentionally prints only the observed address, not the proxy URL, response headers, or raw error objects. Keep TLS verification enabled. For protected API calls, retain the destination's own authentication and attach the agent to the actual client making those requests.

Dockerfile

Create the manifest and lockfile with the installation command above, then use:

FROM node:24-bookworm-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY https.mjs ./
USER node
CMD ["node", "https.mjs"]

View on GitHub