Proxy Configuration Reference

Unified forward proxy configuration for embedding in a server block.

This module defines ProxyConfig, the single entry point for forward proxy settings on a ServerBlock. Listener, TLS, and logging settings are inherited from the enclosing server block and root config — the proxy config only contains proxy-specific concerns.

For a standalone proxy config file, see ElideProxy.pkl which provides a simpler top-level interface that wraps this module.

Usage within a server block:

[":8080"] {
  proxy {
    mitm {}
    recording {}
  }
}

> This page is auto-generated from the PKL schema. See the guide for usage examples.

Types

UpstreamProxyScheme

Protocol used to connect to an upstream (chained) proxy.

• "http" — HTTP CONNECT proxy (most corporate proxies)
• "https" — HTTPS proxy with TLS to the proxy itself
• "socks5" — SOCKS5 gateway

typealias UpstreamProxyScheme = "http" | "https" | "socks5"

---

UpstreamProxy

Upstream proxy for chaining requests through a corporate proxy or SOCKS gateway.

When configured, all outbound connections from elide fwd are routed through this upstream proxy instead of connecting directly to the destination.

upstream {
  url = "http:<<>>
  bypass { "localhost"; "*.internal.corp" }
}

url

Full URL of the upstream proxy, including scheme and port.

url = "http:<<>>
url = "socks5://gateway:1080"

bypass

Hostnames or patterns that bypass the upstream proxy and connect directly. Uses glob syntax. Equivalent to the NO_PROXY environment variable. CIDR ranges are also accepted.

bypass { "localhost"; "*.internal.corp"; "10.0.0.0/8" }

username

Username for HTTP Basic authentication to the upstream proxy. Only used when the upstream requires proxy authentication.

password

Password for HTTP Basic authentication to the upstream proxy. Only used when username is also set.

---

ProxyConnectionSettings

Connection pool and timeout settings for outbound connections to upstream targets.

maxUpstreamConnections

Maximum number of concurrent outbound connections pooled across all upstream targets. New requests block when this limit is reached until an existing connection becomes available. Default: 4096.

connectTimeout

Maximum time to wait for a TCP connection to be established to the upstream target. Applies to both direct connections and connections through a chained UpstreamProxy. Default: 10.s.

responseTimeout

Maximum time to wait for the upstream to send the first byte of its response after the request has been fully sent. Default: 120.s.

idleTimeout

How long an idle keep-alive connection is held open in the pool before being closed. Lower values reclaim resources faster; higher values reduce connection setup overhead for repeated requests. Default: 60.s.

---

InspectorSettings

Inspector API settings for live traffic viewing.

The inspector exposes a local WebSocket endpoint that the Elide desktop app connects to for real-time request/response inspection. By default it listens on a Unix domain socket so that only local processes can connect.

To expose the inspector over TCP (e.g., for remote debugging):

inspector {
  listen = "127.0.0.1:9100"
}

enabled

Whether to start the inspector WebSocket endpoint. When false, no inspector is available and the desktop app cannot connect. Default: true.

listen

Listen address for the inspector endpoint. Accepts a Unix socket path ("unix:///path/to/sock") or a TCP address ("host:port"). The default Unix socket restricts access to local processes only.

---

ProxyConfig

Forward proxy configuration.

When set on a ServerBlock, that block accepts forward proxy requests (HTTP absolute-URI form and HTTPS CONNECT tunnels) in addition to normal route-matched requests.

Minimal usage — MITM-enabled recording proxy:

proxy {
  mitm {}
  recording {}
}

mitm

MITM TLS interception settings. When null (the default), CONNECT tunnels pass through as opaque TCP relays and the proxy cannot inspect or modify HTTPS traffic. Set to new MitmConfig {} to enable interception with default settings. See MitmConfig for CA and certificate options.

access

Access control for proxy clients and upstream destinations. Controls which client IPs may connect and which hosts/ports they may reach. When null, all clients and all destinations are permitted. See AccessControl for allow/deny rules.

rules

Interception rules evaluated in declaration order against each request's target URL. The first matching rule determines the action (allow, block, record, or modify). Requests matching no rule are allowed through unmodified. See ProxyRule for match conditions and actions.

recording

Traffic recording settings for the inspector UI. When null, no request/response data is captured. Set to new RecordingConfig {} to enable recording with defaults. See RecordingConfig for buffer size, body capture, and export options.

upstream

Upstream proxy for chaining outbound connections through a corporate proxy or SOCKS gateway. When null, the proxy connects directly to destination hosts. See UpstreamProxy for bypass and auth settings.

connections

Connection pool and timeout settings for outbound connections. The defaults are suitable for most use cases. See ProxyConnectionSettings for tunable limits.

inspector

Inspector WebSocket API for the Elide desktop app. Enabled by default. See InspectorSettings for listen address options.

---