proxy-agent

Maps HTTP, HTTPS, SOCKS, and PAC proxy protocols to the correct Node.js http.Agent implementation automatically.

Library
npm
v8.0.2
1,168 stars
MIT License

Repository Health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum. How we score it →
70 /100 Good
Development Activity 56
Maintenance 60
Community 76
Maturity 60
Momentum 28

Technical Analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation. How we score it →
84 /100 Excellent
Architecture 88
Code Quality 85
Innovation 82
Learning Curve 80

proxy-agent is a Node.js http.Agent that transparently routes outbound HTTP and HTTPS requests through whatever proxy your environment dictates. It reads the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY variables (via proxy-from-env) and, based on the proxy URL’s protocol, delegates to the appropriate low-level agent — http-proxy-agent, https-proxy-agent, socks-proxy-agent, or pac-proxy-agent.

Instead of wiring up per-protocol proxy logic yourself, you construct a single ProxyAgent and pass it to any Node HTTP client. An internal LRU cache re-uses agent instances across requests to the same proxy, so repeated calls stay cheap. It is the top-level convenience package in TooTallNate’s proxy-agents monorepo and is depended on across the npm ecosystem.

What You Get

  • A single ProxyAgent class that plugs into any Node.js HTTP/HTTPS client
  • Automatic protocol-to-agent mapping across http, https, socks(4/5), and pac+* proxy URLs
  • Environment-variable-driven proxy selection via proxy-from-env (HTTP_PROXY / HTTPS_PROXY / NO_PROXY)
  • An LRU cache that transparently re-uses agent instances for repeated requests to the same proxy
  • First-class TypeScript types and a pluggable getProxyForUrl callback for dynamic proxy resolution

Common Use Cases

  • Making outbound HTTP requests from apps that must honor corporate proxy settings
  • Supporting multiple proxy protocols (SOCKS, HTTP, PAC) behind one agent without branching code
  • Routing traffic through PAC-file-configured proxies in enterprise environments
  • Adding proxy support to CLI tools and libraries that accept a standard http.Agent

Under The Hood

Architecture — The entire public surface lives in packages/proxy-agent/src/index.ts (~183 lines). ProxyAgent extends Agent from agent-base, so it slots into Node’s standard http.Agent contract. A static proxies map keys every supported protocol (http, https, socks/socks4/socks4a/socks5/socks5h, pac+data/file/ftp/http/https) to a pair of lazy loaders — one agent constructor for plaintext requests and one for secure/WebSocket requests. The core connect(req, opts) method reconstructs the request URL from the host header and req.path, calls getProxyForUrl to resolve a proxy string, and short-circuits to a default httpAgent/httpsAgent when no proxy applies. Otherwise it builds an LRU cache key of protocol+proxy, and on a miss parses the proxy URL, validates its protocol, dynamically imports the matching underlying agent, instantiates it, and caches it.

Tech Stack — Written in TypeScript targeting Node.js >= 20, shipped as ESM ("type": "module"). Runtime dependencies are the sibling monorepo agents (agent-base, http-proxy-agent, https-proxy-agent, socks-proxy-agent, pac-proxy-agent, all workspace:*) plus lru-cache for instance caching, proxy-from-env for env-var proxy resolution, and debug for tracing. Built with tsc, tested with Vitest, linted with ESLint; the monorepo uses pnpm workspaces and Turborepo.

Code Quality — Tight, single-file implementation with clear separation between the protocol table, validation (isValidProtocol type guard), and the connect flow. Types are precise: ProxyAgentOptions is an intersection of every underlying agent’s option type, and ValidProtocol is derived from the agents’ own protocols tuples. debug calls trace cache hits and proxy decisions. The package ships a dedicated test/test.ts (~390 lines) exercising real HTTP/HTTPS/SOCKS proxy servers, so behavior is well covered rather than merely unit-mocked.

API Design — Minimal and ergonomic: new ProxyAgent() with zero arguments covers the common case, since routing is inferred entirely from environment variables, and the agent drops into any client that accepts an http.Agent. Advanced control is available through a single options object and an optional getProxyForUrl callback for dynamic resolution. The README’s protocol table and one-call example make onboarding fast; the main friction is understanding upstream proxy-from-env env-var semantics.

Used by 71 apps in this directory

JavaScript
86%
AGPL 3.0

SillyTavern

AI Assistants

35,357

The power-user LLM frontend that unifies dozens of AI backends with a rich scripting engine, immersive Visual Novel mode, and a thriving extension ecosystem.

View details
86
Repo Health
71
Technical
63
Dependency
Built with
JavaScript 86%
Updated 1 months ago
JavaScript
100%
AGPL 3.0

Social Analyzer

Security

24,489

Find and analyze a person's digital footprint across 1000+ social media platforms using multi-layer detection, OCR, and metadata extraction.

View details
42
Repo Health
52
Technical
69
Dependency
Built with
JavaScript 100%
Updated 10 months ago
TypeScript
91%
MIT

Super Productivity

Productivity · Project Management

23,461

A privacy-respecting, local-first task manager with built-in timeboxing, Pomodoro timer, and deep integrations for Jira, GitHub, GitLab, and CalDAV — no accounts, no data collection, ever.

View details
91
Repo Health
81
Technical
69
Dependency
Built with
TypeScript 91%
Updated 1 weeks ago
TypeScript
96%
Other

superglue

AI Agents · Data Engineering · Developer Tools

2,070

superglue is an AI-agent-driven integration engine that turns plain-English descriptions of enterprise systems into production-grade API tools, ERP/CRM connectors, and data pipelines — self-hosted or cloud, Y Combinator-backed (W25).

View details
51
Repo Health
79
Technical
67
Dependency
Built with
TypeScript 96%
Updated 3 weeks ago
JavaScript
51%
MIT

Uptime Kuma

Monitoring

93,330

Self-hosted monitoring for every service you run — 23 monitor types, 95 notification channels, live dashboards, and public status pages with no vendor lock-in.

View details
92
Repo Health
81
Technical
62
Dependency
Built with
JavaScript 51%
Vue 37%
TypeScript 11%
Updated 1 weeks ago
JavaScript
51%
MIT

Uptime Kuma

Monitoring

93,330

Self-hosted monitoring for every service you run — 23 monitor types, 95 notification channels, live dashboards, and public status pages with no vendor lock-in.

View details
92
Repo Health
81
Technical
62
Dependency
Built with
JavaScript 51%
Vue 37%
TypeScript 11%
Updated 1 weeks ago
JavaScript
51%
MIT

Uptime Kuma

Monitoring

93,330

Self-hosted monitoring for every service you run — 23 monitor types, 95 notification channels, live dashboards, and public status pages with no vendor lock-in.

View details
92
Repo Health
81
Technical
62
Dependency
Built with
JavaScript 51%
Vue 37%
TypeScript 11%
Updated 1 weeks ago
Python
48%
AGPL 3.0

VoiceStudio

Mcp · Music Audio · Voice AI

102,997

Open-source, fully local ElevenLabs alternative for voice cloning, voice design, video dubbing, dictation, transcription and audiobooks, with a local API and MCP server for agents.

View details
86
Repo Health
83
Technical
70
Dependency
Built with
Python 48%
TypeScript 22%
JavaScript 19%
Updated 1 weeks ago

Join founders buildingwith open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on Substack
Join 750+ subscribers