{"id":17237,"library":"global-agent","title":"Global Agent","description":"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.","status":"active","version":"4.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/gajus/global-agent","tags":["javascript","http","global","proxy","agent","typescript"],"install":[{"cmd":"npm install global-agent","lang":"bash","label":"npm"},{"cmd":"yarn add global-agent","lang":"bash","label":"yarn"},{"cmd":"pnpm add global-agent","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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'.","wrong":"const globalAgent = require('global-agent/bootstrap');","symbol":"Side-effect bootstrap","correct":"import 'global-agent/bootstrap';"},{"note":"Use this named import if you need to explicitly control when the agent is bootstrapped, such as conditionally.","wrong":"const { bootstrap } = require('global-agent');","symbol":"bootstrap","correct":"import { bootstrap } from 'global-agent';"},{"note":"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`.","wrong":"const { createGlobalProxyAgent } = require('global-agent');","symbol":"createGlobalProxyAgent","correct":"import { createGlobalProxyAgent } from 'global-agent';"},{"note":"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.","wrong":"import { GLOBAL_AGENT } from 'global-agent';","symbol":"GlobalAgent","correct":"declare var global: { GLOBAL_AGENT: GlobalProxyAgent };"}],"quickstart":{"code":"import 'global-agent';\nimport http from 'node:http';\n\n// Simulate setting the environment variable\nprocess.env.GLOBAL_AGENT_HTTP_PROXY = process.env.GLOBAL_AGENT_HTTP_PROXY ?? 'http://127.0.0.1:8080';\n\nconsole.log(`Global agent will use proxy: ${process.env.GLOBAL_AGENT_HTTP_PROXY}`);\n\n// In a real scenario, you'd run this script with the environment variable set:\n// export GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8080 && node your-script.js\n\n// To explicitly bootstrap if not using the side-effect import:\n// import { bootstrap } from 'global-agent';\n// bootstrap();\n\nconst options = {\n  hostname: 'example.com',\n  port: 80,\n  path: '/',\n  method: 'GET'\n};\n\nconst req = http.request(options, (res) => {\n  console.log(`STATUS: ${res.statusCode}`);\n  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);\n  res.setEncoding('utf8');\n  let data = '';\n  res.on('data', (chunk) => {\n    data += chunk;\n  });\n  res.on('end', () => {\n    console.log('Response body length:', data.length);\n  });\n});\n\nreq.on('error', (e) => {\n  console.error(`Problem with request: ${e.message}`);\n});\n\nreq.end();","lang":"typescript","description":"Demonstrates how to enable global HTTP/HTTPS proxying using the side-effect import and environment variables, then makes a sample HTTP request."},"warnings":[{"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.","message":"Starting 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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"The `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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"`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`).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update your import statements to use named exports: `import { bootstrap } from 'global-agent';` or `import { createGlobalProxyAgent } from 'global-agent';`.","message":"Version 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.","severity":"breaking","affected_versions":">=4.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"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).","error":"Error: self signed certificate in certificate chain"},{"fix":"Export `GLOBAL_AGENT_HTTP_PROXY` (e.g., `export GLOBAL_AGENT_HTTP_PROXY=http://localhost:8080`) instead of `HTTP_PROXY`.","cause":"You are likely using the `HTTP_PROXY` environment variable, but `global-agent` expects `GLOBAL_AGENT_HTTP_PROXY` for its bootstrap module.","error":"Proxy is not being used, even with HTTP_PROXY set."},{"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.","cause":"The `global-agent/bootstrap` module or the `bootstrap()` function has been called more than once in the application lifecycle.","error":"ERR_UNHANDLED_ERROR: Global agent is already initialized."},{"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).","cause":"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.","error":"TypeError: (0, global_agent_1.bootstrap) is not a function"}],"ecosystem":"npm","meta_description":null}