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:

npm i global-proxy-agent

Or with Yarn:

yarn add global-proxy-agent

📦 Usage

1. setupGlobalProxyAgent()

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

import { setupGlobalProxyAgent } from 'global-proxy-agent';

setupGlobalProxyAgent();

2. bootstrap()

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

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

bootstrap();

3. createSmartProxyAgent(url: string): Agent

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

import { createSmartProxyAgent } from 'global-proxy-agent';

const agent = createSmartProxyAgent('https://example.com');

4. resolveProxyForUrl(url: string): string

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

import { resolveProxyForUrl } from 'global-proxy-agent';

const proxy = resolveProxyForUrl('https://example.com');
console.log(proxy); // e.g., http://myproxy.com:8080

5. setGlobalProxy(proxyUrl: string)

Dynamically sets or updates the global proxy at runtime.

import { setGlobalProxy } from 'global-proxy-agent';

setGlobalProxy('http://my-new-proxy.com:8080');

6. setGlobalNoProxy(domains: string[])

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

import { setGlobalNoProxy } from 'global-proxy-agent';

setGlobalNoProxy(['localhost', 'example.com']);

7. globalState

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

import { globalState } from 'global-proxy-agent';

console.log(globalState.proxyUrl);

8. setAgent(agent: Agent)

Override the global agent manually.

import { setAgent } from 'global-proxy-agent';
import { Agent } from 'http';

const customAgent = new Agent();
setAgent(customAgent);

9. getCurrentProxy(): string

Returns the current global proxy URL.

import { getCurrentProxy } from 'global-proxy-agent';

console.log(getCurrentProxy()); // e.g., 'http://proxy:3128'

10. getExcludedDomains(): string[]

Returns the list of domains excluded from proxying.

import { getExcludedDomains } from 'global-proxy-agent';

console.log(getExcludedDomains()); // ['localhost', 'example.com']

11. resetProxySettings()

Resets all proxy settings to defaults.

import { resetProxySettings } from 'global-proxy-agent';

resetProxySettings();

12. enableLogging() / disableLogging()

Enables or disables internal debug logging.

import { enableLogging, disableLogging } from 'global-proxy-agent';

enableLogging();  // Turn on logs
disableLogging(); // Turn off logs

13. logger

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

import { logger } from 'global-proxy-agent';

logger.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)

npm install -g global-proxy-agent

Or use via npx without installing:

npx global-proxy-agent <command>

🧾 Commands

set-proxy <proxyUrl>

Set the global proxy dynamically.

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

unset-proxy

Remove the global proxy configuration.

global-proxy-agent unset-proxy

set-no-proxy <domains>

Specify comma-separated domains to exclude from proxying.

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

show-config

View the current proxy configuration and excluded domains.

global-proxy-agent show-config

reset

Reset all proxy settings to their default state.

global-proxy-agent reset

enable-logging

Enable verbose logging for debugging.

global-proxy-agent enable-logging

disable-logging

Turn off verbose logging.

global-proxy-agent disable-logging

📌 Example

# Set proxy
global-proxy-agent set-proxy http://proxy.local:8080

# Exclude local dev domains
global-proxy-agent set-no-proxy localhost,dev.local

# Check current settings
global-proxy-agent show-config