Registry / http-networking / global-agent

global-agent

library4.1.3jsnpmunverified

global-agent is a Node.js library designed to globally configure HTTP/HTTPS proxy settings for outgoing network requests. It intercepts `http.Agent` and `https.Agent` instances to route traffic through a specified proxy server, configurable primarily via environment variables such as `GLOBAL_AGENT_HTTP_PROXY`, `GLOBAL_AGENT_HTTPS_PROXY`, and `GLOBAL_AGENT_NO_PROXY`. The current stable version is 4.1.3, released in March 2026, indicating an active development and maintenance status. The project maintains a steady release cadence, with multiple minor and patch updates in early 2026. Key differentiators include its simple bootstrap mechanism for seamless global integration across applications, support for dynamic runtime re-configuration of proxy settings, and its intentional design to override other explicitly configured HTTP agents. It distinguishes itself by primarily using its own set of environment variables rather than strictly adhering to the standard `HTTP_PROXY` convention for its main bootstrap module.

http-networking devops

npm install global-agent

github ↗package ↗

INSTALL

IMPORT

SIG · GLOBAL-AGENT

global-agent

http-networkingjavascriptv4.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Side-effect bootstrap

✓ import 'global-agent/bootstrap';

✗ const globalAgent = require('global-agent/bootstrap');

This is a side-effect import that initializes the global proxy agent based on environment variables. It's the most common way to set up 'global-agent'.

bootstrap

✓ import { bootstrap } from 'global-agent';

✗ const { bootstrap } = require('global-agent');

Use this named import if you need to explicitly control when the agent is bootstrapped, such as conditionally.

createGlobalProxyAgent

✓ import { createGlobalProxyAgent } from 'global-agent';

✗ const { createGlobalProxyAgent } = require('global-agent');

Use this named import to create a controlled instance of the global proxy agent without affecting the global scope or relying on `global.GLOBAL_AGENT`.

GlobalAgent

✓ declare var global: { GLOBAL_AGENT: GlobalProxyAgent };

✗ import { GLOBAL_AGENT } from 'global-agent';

After `bootstrap` or `global-agent/bootstrap` is called, the configuration object is available at `global.GLOBAL_AGENT`. It is not directly exportable via named imports.

Demonstrates how to enable global HTTP/HTTPS proxying using the side-effect import and environment variables, then makes a sample HTTP request.

import 'global-agent'; import http from 'node:http'; // Simulate setting the environment variable process.env.GLOBAL_AGENT_HTTP_PROXY = process.env.GLOBAL_AGENT_HTTP_PROXY ?? 'http://127.0.0.1:8080'; console.log(`Global agent will use proxy: ${process.env.GLOBAL_AGENT_HTTP_PROXY}`); // In a real scenario, you'd run this script with the environment variable set: // export GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8080 && node your-script.js // To explicitly bootstrap if not using the side-effect import: // import { bootstrap } from 'global-agent'; // bootstrap(); const options = { hostname: 'example.com', port: 80, path: '/', method: 'GET' }; const req = http.request(options, (res) => { console.log(`STATUS: ${res.statusCode}`); console.log(`HEADERS: ${JSON.stringify(res.headers)}`); res.setEncoding('utf8'); let data = ''; res.on('data', (chunk) => { data += chunk; }); res.on('end', () => { console.log('Response body length:', data.length); }); }); req.on('error', (e) => { console.error(`Problem with request: ${e.message}`); }); req.end();

Debug

Known issues

breakingStarting from v4.0.0, `rejectUnauthorized` for TLS connections defaults to `true`. This aligns with Node.js's default behavior but means connections to servers with self-signed or otherwise invalid TLS certificates will now be rejected by default.

fix

To allow connections to servers with self-signed certificates, set the environment variable `GLOBAL_AGENT_SKIP_HTTPS_VALIDATION=true`. Be aware of the security implications of disabling certificate validation.

affects: >=4.0.0

gotchaThe `global-agent/bootstrap` module and `bootstrap()` function primarily rely on `GLOBAL_AGENT_HTTP_PROXY` and `GLOBAL_AGENT_HTTPS_PROXY` environment variables, not the standard `HTTP_PROXY` or `HTTPS_PROXY`.

fix

Always use `GLOBAL_AGENT_HTTP_PROXY`, `GLOBAL_AGENT_HTTPS_PROXY`, and `GLOBAL_AGENT_NO_PROXY` environment variables for configuration when using the bootstrap mechanism.

affects: >=1.0.0

gotcha`global-agent` is designed to aggressively override any explicitly configured `http.Agent` or `https.Agent` instances that are passed to Node.js's native `http`/`https` modules or popular libraries built on top of them (like `axios`).

fix

Be aware that `global-agent` will likely supersede other proxy configurations. If you need fine-grained control over specific requests, consider using `createGlobalProxyAgent` to get a controlled instance or disable `global-agent` for those specific parts of your application.

affects: >=1.0.0

breakingVersion 4.1.0 changed direct function exports to strictly named exports. While the side-effect `import 'global-agent/bootstrap'` remains, direct imports of functions like `bootstrap` and `createGlobalProxyAgent` must now use named import syntax.

fix

Update your import statements to use named exports: `import { bootstrap } from 'global-agent';` or `import { createGlobalProxyAgent } from 'global-agent';`.

affects: >=4.1.0

Errors

Common errors & fixes

Error: self signed certificate in certificate chain

The proxy server or target server is using a self-signed or untrusted SSL/TLS certificate, and `global-agent`'s `rejectUnauthorized` is `true` (default since v4.0.0).

fix

Set `GLOBAL_AGENT_SKIP_HTTPS_VALIDATION=true` in your environment variables to bypass certificate validation. Use with caution as it disables security checks. For production, ensure your proxy uses trusted certificates or configure your system to trust the self-signed certificate.

Proxy is not being used, even with HTTP_PROXY set.

You are likely using the `HTTP_PROXY` environment variable, but `global-agent` expects `GLOBAL_AGENT_HTTP_PROXY` for its bootstrap module.

fix

Export `GLOBAL_AGENT_HTTP_PROXY` (e.g., `export GLOBAL_AGENT_HTTP_PROXY=http://localhost:8080`) instead of `HTTP_PROXY`.

ERR_UNHANDLED_ERROR: Global agent is already initialized.

The `global-agent/bootstrap` module or the `bootstrap()` function has been called more than once in the application lifecycle.

fix

Ensure `import 'global-agent/bootstrap';` or `bootstrap();` is only executed once. If using conditional logic, wrap it carefully or use `createGlobalProxyAgent` for non-global instances.

TypeError: (0, global_agent_1.bootstrap) is not a function

This error typically occurs when attempting to use a CommonJS `require()` syntax (e.g., `const { bootstrap } = require('global-agent');`) for named exports in a context where `global-agent` primarily provides ESM named exports, or when a default import was expected but named imports are now required.

fix

Switch to ES module import syntax: `import { bootstrap } from 'global-agent';`. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or `.mjs` file extension).

Upgrade

Version history

4.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/gajus/global-agent ↗

packagehttps://www.npmjs.com/package/global-agent ↗