API Reference

Every public export, with the exact shape from src/index.ts, src/connect.ts, and src/node-http.ts.

#Functions

#`installProxyline(options): ProxylineHandle`

Aliased as installGlobalProxy. Installs the runtime and returns a handle.

Throws ProxylineError with code MANAGED_PROXY_URL_REQUIRED if mode: "managed" is used without a proxyUrl.
Throws ProxylineError with code UNSUPPORTED_PROXY_PROTOCOL if managed-mode proxyUrl is not http:// or https://.
Throws ProxylineError with code RUNTIME_ALREADY_ACTIVE if another Proxyline runtime is already installed and ifActive is omitted or cannot safely reuse the active runtime.

In managed mode (and active ambient mode), installProxyline:

Captures originals for http.request, http.get, http.globalAgent, https.request, https.get, https.globalAgent.
Captures the current undici global dispatcher and fetch globals.
Installs patched http.request/get, https.request/get.
Replaces http.globalAgent and https.globalAgent with Proxyline's HTTP/HTTPS Node agent.
Calls undici.setGlobalDispatcher with a ProxyAgent (managed) or Proxyline's ambient dispatcher (ambient), and patches globalThis.fetch plus Request, Response, Headers, and FormData to use that dispatcher-compatible fetch stack.
Emits runtime.installed.

In inactive ambient mode (no supported proxy env variables), no patches are installed; the handle returns a passive observer with active: false.

#`openProxyConnectTunnel(options): Promise<net.Socket | tls.TLSSocket>`

Opens a one-shot HTTP CONNECT tunnel through a proxy. See Surfaces — HTTP CONNECT tunnel.

#`hasAmbientNodeProxyConfigured(options?): boolean`

Returns true when the ambient proxy environment would proxy a probe URL for the requested protocol. Defaults to protocol: "https".

hasAmbientNodeProxyConfigured({ protocol: "https" });

#`createAmbientNodeProxyAgent(options?): http.Agent | undefined`

Returns a Proxyline-backed Node agent when ambient env proxy settings apply, or undefined when no proxy is configured for the requested protocol. This is for libraries that accept a Node agent option but should stay direct when the operator has no proxy env configured.

const agent = createAmbientNodeProxyAgent({
  protocol: "https",
  proxyTls: { caFile: "/etc/proxy-ca.pem" },
});

#`redactProxyUrl(value: string | URL): string`

Strips userinfo, search, and fragment from a URL. Used internally to keep events and decisions free of credentials. Safe to use on log lines you build yourself.

redactProxyUrl("https://user:secret@proxy.example:8443/path?q=1#frag");
// → "https://proxy.example:8443/path"

#`resolveProxyTlsCa(options): string | undefined`

Resolves a ProxylineTlsOptions value to a PEM string by reading caFile from disk if needed. Returns undefined when no CA material is supplied. Exposed so callers can pre-resolve before passing values into their own TLS-using code.

#Classes

#`ProxylineError extends Error`

class ProxylineError extends Error {
  readonly code: string;
  readonly name: "ProxylineError";
}

Codes:

MANAGED_PROXY_URL_REQUIRED — mode: "managed" was used without proxyUrl.
UNSUPPORTED_PROXY_PROTOCOL — proxy URL scheme is not http:// or https://.
RUNTIME_ALREADY_ACTIVE — another Proxyline runtime is already installed.
CONNECT_FAILED — openProxyConnectTunnel failed (bad response, timeout, header overrun, or socket error).
INVALID_CONNECT_TARGET — openProxyConnectTunnel received an empty or unsafe target host, invalid bracket syntax, or an invalid target port.

#Types

#`ProxylineMode`

type ProxylineMode = "managed" | "ambient";

See Modes.

#`ProxylineSurface`

type ProxylineSurface =
  | "node-http"
  | "node-https"
  | "undici"
  | "websocket"
  | "connect"
  | "unknown";

Used in explain() decisions and event payloads to identify which network surface a decision is for. Pass it via explain(url, { surface }).

#`ProxylineOptions`

type ProxylineOptions = Readonly<{
  mode: ProxylineMode;
  proxyUrl?: string | URL;
  proxyTls?: ProxylineTlsOptions;
  bypassPolicy?: ProxylineBypassPolicy;
  ifActive?: "error" | "reuse-compatible" | "replace";
  onEvent?: (event: ProxylineEvent) => void;
  undici?: ProxylineUndiciOptions;
}>;

mode — required. "managed" or "ambient".
proxyUrl — required in managed mode, ignored in ambient mode. Managed-mode URLs must be http:// or https://.
proxyTls — CA trust scoped to the proxy endpoint. See Proxy TLS.
bypassPolicy — managed-mode escape hatch for trusted traffic that should go direct. Ignored in ambient mode.
ifActive — process singleton behavior when Proxyline is already active. Defaults to "error". "reuse-compatible" returns the active handle when mode/proxy/TLS/bypass/undici settings match; ambient mode also requires the captured proxy env snapshot to match. "replace" stops the active runtime before installing the new one.
onEvent — callback fired with every ProxylineEvent.
undici — default options for Proxyline-owned undici dispatchers.

#`ProxylineUndiciOptions`

type ProxylineUndiciOptions = Readonly<{
  allowH2?: boolean;
  bodyTimeout?: number;
  headersTimeout?: number;
  connect?: Readonly<{
    autoSelectFamily?: boolean;
    autoSelectFamilyAttemptTimeout?: number;
  }>;
}>;

These options apply to the global dispatcher installed by installGlobalProxy() and to dispatchers returned by createUndiciDispatcher().

#`ProxylineTlsOptions`

type ProxylineTlsOptions = Readonly<{
  ca?: string;     // PEM string
  caFile?: string; // path read with fs.readFileSync(..., "utf8")
}>;

When both are provided, ca wins.

#`ProxylineDecision`

type ProxylineDecision = Readonly<{
  kind: "proxied" | "direct" | "blocked";
  reason: string;
  surface: ProxylineSurface;
  url: string;
  proxyUrl?: string; // redacted
}>;

Known reason values:

"managed-proxy-active" — managed mode applied.
"managed-proxy-bypass-policy" — managed mode was active, but bypassPolicy intentionally sent the URL direct.
"managed-proxy-unsupported-url-scheme" — managed mode is active, but the URL scheme is not one Proxyline can proxy.
"ambient-proxy-active" — ambient mode resolved a proxy from env.
"ambient-proxy-not-configured" — ambient mode has no proxy env set, or the URL scheme is unsupported.
"no-proxy-match" — the URL matched NO_PROXY.
"runtime-stopped" — explain() was called after stop().

kind: "blocked" is reserved for future explicit deny rules; the current implementation does not produce blocked decisions.

#`ProxylineBypassRequest`

type ProxylineBypassRequest = Readonly<{
  surface: ProxylineSurface;
  url: string;
}>;

#`ProxylineBypassPolicy`

type ProxylineBypassPolicy = (request: ProxylineBypassRequest) => boolean;

Return true to send that managed-mode request direct. Use this only for explicitly trusted destinations such as loopback control-plane endpoints.

#`ProxylineEvent`

type ProxylineEvent =
  | Readonly<{ type: "runtime.installed"; mode: ProxylineMode; active: boolean; proxyUrl?: string }>
  | Readonly<{ type: "runtime.stopped"; mode: ProxylineMode }>
  | Readonly<{ type: "decision"; decision: ProxylineDecision }>
  | Readonly<{ type: "warning"; code: string; message: string }>;

decision events fire from inside explain(). runtime.installed and runtime.stopped fire from installProxyline and handle.stop() respectively. warning is reserved for future runtime diagnostics.

#`ExplainOptions`

type ExplainOptions = Readonly<{
  surface?: ProxylineSurface;
}>;

#`ProxylineHandle`

type ProxylineHandle = Readonly<{
  mode: ProxylineMode;
  active: boolean;
  proxyUrl?: string;
  createNodeAgent: () => http.Agent;
  createUndiciDispatcher: () => Dispatcher;
  createWebSocketAgent: () => http.Agent;
  explain: (url: string | URL, options?: ExplainOptions) => ProxylineDecision;
  registerBypass: (registration: ProxylineBypassRegistration) => () => void;
  stop: () => void;
  withBypass: <T>(registration: ProxylineBypassRegistration, run: () => T) => T;
}>;

mode — the mode this handle was installed with.
active — true when the runtime is installed and forcing/respecting a proxy.
proxyUrl — redacted proxy URL string when active.
createNodeAgent() — proxy-aware http.Agent for ad-hoc node:http(s) use. Returns a direct agent when inactive or after stop().
createUndiciDispatcher() — proxy-aware undici Dispatcher. Returns a direct UndiciAgent() when ambient-inactive or after stop().
createWebSocketAgent() — same as createNodeAgent() but typed for WebSocket clients.
explain(url, options?) — returns a ProxylineDecision and emits a decision event.
registerBypass({ url, surface? }) — managed-mode process-wide bypass. Returns an unregister callback. When surface is omitted, the bypass matches any surface for that exact URL.
stop() — restores the captured Node HTTP(S) stack, undici dispatcher, and fetch globals, destroys Proxyline-owned runtime agents/dispatchers, emits runtime.stopped. Idempotent.
withBypass(registration, run) — applies a bypass only to run() and async work created inside that callback.

#Dispatcher Detection

isProxylineDispatcher(dispatcher: unknown): boolean;

Returns true for Proxyline-owned managed and ambient undici dispatchers. Use this instead of constructor-name checks when integrating with code that also manages undici globals. Import from @openclaw/proxyline/dispatcher-brand when detection must not load Proxyline's full runtime.

#`OpenProxyConnectTunnelOptions`

type OpenProxyConnectTunnelOptions = Readonly<{
  proxyUrl: string | URL;
  proxyTls?: ProxylineTlsOptions;
  targetHost: string;
  targetPort: number;
  timeoutMs?: number;
}>;

proxyUrl — http:// or https://. Userinfo becomes a Proxy-Authorization: Basic header.
proxyTls — CA trust for HTTPS proxies. See Proxy TLS.
targetHost / targetPort — what to ask the proxy to connect to.
timeoutMs — overall budget for the CONNECT handshake.

#`AmbientNodeProxyAgentOptions`

type AmbientNodeProxyAgentOptions = {
  env?: ProxyEnvSnapshot;
  protocol?: "http" | "https";
  proxyTls?: ProxylineTlsOptions;
};

env — optional env snapshot. Defaults to reading process env.
protocol — probe protocol, defaulting to "https".
proxyTls — CA trust for HTTPS proxy endpoints. See Proxy TLS.

API Reference

#Functions

#installProxyline(options): ProxylineHandle

#openProxyConnectTunnel(options): Promise<net.Socket | tls.TLSSocket>

#hasAmbientNodeProxyConfigured(options?): boolean

#createAmbientNodeProxyAgent(options?): http.Agent | undefined

#redactProxyUrl(value: string | URL): string

#resolveProxyTlsCa(options): string | undefined

#Classes

#ProxylineError extends Error

#Types

#ProxylineMode

#ProxylineSurface

#ProxylineOptions

#ProxylineUndiciOptions

#ProxylineTlsOptions

#ProxylineDecision

#ProxylineBypassRequest

#ProxylineBypassPolicy

#ProxylineEvent

#ExplainOptions

#ProxylineHandle