Proxyline installs one process-wide proxy policy across Node's built-in HTTP(S) clients, global fetch and Undici, compatible WebSocket clients, and explicit CONNECT tunnels. It is for Node applications that need one runtime to enforce proxy routing, explain its decisions, and restore the original networking globals.

Documentation is available at proxyline.dev.

pnpm add @openclaw/proxyline undici@^8.12.2

Or with npm:

npm install @openclaw/proxyline undici@^8.12.2

Proxyline requires Node.js 22.19.0 or newer and a host undici version in the >=8.12.2 <9 range. The package is ESM-only and includes TypeScript declarations. The Undici minimum includes fixes for TLS validation, redirects, and denial-of-service vulnerabilities.

Proxyline imports the installed Undici peer entrypoint explicitly, including when loaded under Bun, so its fetch classes and dispatcher cleanup use the same implementation. The static import also lets Node-targeted bundlers include that peer in standalone output.

Save this as proxy.mjs:

import { installGlobalProxy } from "@openclaw/proxyline";

const proxy = installGlobalProxy({
  mode: "managed",
  proxyUrl: "http://127.0.0.1:3128",
});
console.log(proxy.explain("https://api.example.com/").reason);
proxy.stop();

node proxy.mjs
# managed-proxy-active

This asks Proxyline for a routing decision without connecting to the placeholder proxy. Install Proxyline before loading application or plugin code that may capture networking functions.

Proxyline has two explicit routing modes:

Managed mode fails during setup when its proxy configuration is missing or unsupported. Ambient mode reads the environment once at installation and stays inactive when no supported HTTP or HTTPS proxy is configured. See Modes and Environment Variables for the complete rules.

proxy.createNodeAgent() and proxy.createUndiciDispatcher() expose the same policy to libraries that accept an agent or dispatcher directly. The surface guide describes ownership, TLS preservation, and cleanup for each API.

Managed mode supports deliberate direct-routing exceptions. A bypassPolicy handles installation-time policy, registerBypass() registers an exact process-wide exception, and withBypass() limits an exception to one async context. Each decision remains visible through explain().

For an HTTPS proxy with a private CA, use proxyTls.ca or proxyTls.caFile. That trust applies only to the proxy connection; destination TLS validation remains separate. See Proxy TLS.

Standalone Node helper agents support prepared DNS lookups and proxy client certificates through createAmbientNodeProxyAgent({ resolveProxyConnectOptions }). Raw CONNECT callers pass the same controls through proxyConnect. The selected proxy URL retains ownership of the connection host and port. See the connection controls.

proxy.explain(url) reports proxied or direct, the reason, the surface, and a credential-redacted proxy URL when one applies. The optional onEvent callback receives installation, shutdown, and decision events.

Only one Proxyline runtime is active in a process. A second installation fails by default; ifActive can reuse a compatible runtime or replace it intentionally. proxy.stop() restores the captured Node HTTP(S) methods, global agents, Undici dispatcher, and fetch globals. See Observability and the API Reference.

Proxyline is a Node-process runtime, not an operating-system sandbox. Raw net or tls sockets, native or private transport stacks, networking functions captured before installation, and DNS traffic are outside its boundary. Combine it with operating-system egress controls when code in the process is not trusted.

Read the security model before treating managed mode as an enforcement boundary.

• Getting Started
• Modes
• Surfaces
• API Reference
• Environment Variables
• Proxy TLS
• Observability
• Security
• Troubleshooting
• Testing

pnpm install --frozen-lockfile
pnpm check
pnpm test
pnpm docs:build

Releases require an annotated SSH-signed v<package.json version> tag from a key in the committed .github/release-allowed-signers. The tag must target the checked-out commit. The npm workflow freezes the tag object and source commit, then rechecks both remote identities before publishing or reporting an already-published version. A replacement tag at the same commit is rejected.

Manual dispatch may select a branch whose matching version tag targets that commit. Enable dry_run to check and pack a branch before its tag exists; this mode never publishes. Publishing uses the existing npm-release environment and OIDC trusted publisher; do not publish locally.

MIT