global-proxy-agent

A universal proxy agent for Node.js that combines environment-variable-based proxy resolution with smart protocol-aware agent selection. Automatically supports HTTP, HTTPS, SOCKS, and PAC proxies using a modular, runtime-configurable approach.

Additionally, global-proxy-agent includes a powerful CLI for managing proxy settings directly from the terminal. This allows users to configure proxies, excluded domains, and logging without writing any code.

Installation

To install global-proxy-agent, use npm:

1npm i global-proxy-agent

Or with Yarn:

1yarn add global-proxy-agent

---

📦 Usage

1. setupGlobalProxyAgent()

Initializes the global proxy agent system. Should be called before using any global proxy features.

1import { setupGlobalProxyAgent } from 'global-proxy-agent';
2
3setupGlobalProxyAgent();

---

2. bootstrap()

Bootstraps the proxy settings using environment variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, etc).

1import { bootstrap } from 'global-proxy-agent';
2
3bootstrap();

---

3. createSmartProxyAgent(url: string): Agent

Creates an HTTP(S) agent for a specific request URL, using the appropriate proxy.

1import { createSmartProxyAgent } from 'global-proxy-agent';
2
3const agent = createSmartProxyAgent('https://example.com');

---

4. resolveProxyForUrl(url: string): string

Returns the resolved proxy URL that would be used for the given request URL.

1import { resolveProxyForUrl } from 'global-proxy-agent';
2
3const proxy = resolveProxyForUrl('https://example.com');
4console.log(proxy); // e.g., http://myproxy.com:8080

---

5. setGlobalProxy(proxyUrl: string)

Dynamically sets or updates the global proxy at runtime.

1import { setGlobalProxy } from 'global-proxy-agent';
2
3setGlobalProxy('http://my-new-proxy.com:8080');

---

6. setGlobalNoProxy(domains: string[])

Sets domains to be excluded from the proxy (similar to NO_PROXY behavior).

1import { setGlobalNoProxy } from 'global-proxy-agent';
2
3setGlobalNoProxy(['localhost', 'example.com']);

---

7. globalState

Access to internal config (not typically needed by end users, but useful for debugging or advanced use cases).

1import { globalState } from 'global-proxy-agent';
2
3console.log(globalState.proxyUrl);

---

8. setAgent(agent: Agent)

Override the global agent manually.

1import { setAgent } from 'global-proxy-agent';
2import { Agent } from 'http';
3
4const customAgent = new Agent();
5setAgent(customAgent);

---

9. getCurrentProxy(): string

Returns the current global proxy URL.

1import { getCurrentProxy } from 'global-proxy-agent';
2
3console.log(getCurrentProxy()); // e.g., 'http://proxy:3128'

---

10. getExcludedDomains(): string[]

Returns the list of domains excluded from proxying.

1import { getExcludedDomains } from 'global-proxy-agent';
2
3console.log(getExcludedDomains()); // ['localhost', 'example.com']

---

11. resetProxySettings()

Resets all proxy settings to defaults.

1import { resetProxySettings } from 'global-proxy-agent';
2
3resetProxySettings();

---

12. enableLogging() / disableLogging()

Enables or disables internal debug logging.

1import { enableLogging, disableLogging } from 'global-proxy-agent';
2
3enableLogging();  // Turn on logs
4disableLogging(); // Turn off logs

---

13. logger

Access the internal logger (uses console.log by default, can be customized).

1import { logger } from 'global-proxy-agent';
2
3logger.log('Custom debug message');

---

CLI Usage

The global-proxy-agent provides a command-line interface to manage your proxy settings easily via terminal.

📥 Install Globally (optional)

1npm install -g global-proxy-agent

Or use via npx without installing:

1npx global-proxy-agent <command>

---

🧾 Commands

set-proxy <proxyUrl>

Set the global proxy dynamically.

1global-proxy-agent set-proxy http://my-proxy.com:3128

unset-proxy

Remove the global proxy configuration.

1global-proxy-agent unset-proxy

set-no-proxy <domains>

Specify comma-separated domains to exclude from proxying.

1global-proxy-agent set-no-proxy localhost,example.com

show-config

View the current proxy configuration and excluded domains.

1global-proxy-agent show-config

reset

Reset all proxy settings to their default state.

1global-proxy-agent reset

enable-logging

Enable verbose logging for debugging.

1global-proxy-agent enable-logging

disable-logging

Turn off verbose logging.

1global-proxy-agent disable-logging

---

📌 Example

1# Set proxy
2global-proxy-agent set-proxy http://proxy.local:8080
3
4# Exclude local dev domains
5global-proxy-agent set-no-proxy localhost,dev.local
6
7# Check current settings
8global-proxy-agent show-config

---