Proxy Rules Reference

Proxy interception rules.

Rules are evaluated in declaration order against the target URL (the URL the client is trying to reach, not the proxy's own address). The first matching rule wins — subsequent rules are not evaluated for that request. Requests that match no rule fall through to the default action ("allow").

Rules can block, record, or modify traffic declaratively. For programmable interception with JavaScript handlers, use the elide:proxy JS API instead of (or in addition to) these declarative rules.

Example — block ads and record API traffic:

rules {
  new { match = "*.doubleclick.net"; action = "block" }
  new { match { host = "api.example.com"; path = "/v1/**" }; action = "record" }
}

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

Types

HttpMethod

Standard HTTP request methods used for rule matching.

typealias HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "TRACE"

RuleAction

Action to take when a request matches a rule.

• "allow" — forward to upstream unmodified (default, zero overhead)
• "block" — reject with an error response; no upstream connection is made
• "record" — forward and capture the full request/response for inspector

• "modify" — apply requestHeaders/responseHeaders transformations

typealias RuleAction = "allow" | "block" | "record" | "modify"

---

ProxyMatch

Match conditions for a proxy rule.

host

Hostname or glob pattern to match against the request's target host.

host = "*.example.com"
host = "api.stripe.com"

path

URL path pattern to match. matches a single path segment; * matches zero or more segments.

path = "/api/**"
path = "/v1/users/*"

methods

HTTP methods to match. When null, matches all methods. When set, only requests using one of the listed methods match this rule.

methods { "GET"; "HEAD" }

---

HeaderOps

Header mutation operations applied to requests or responses.

Operations are applied in order: set, then add, then remove.

requestHeaders {
  set { ["X-Forwarded-For"] = "10.0.0.1" }
  remove { "Cookie" }
}

set

Headers to set unconditionally. If a header already exists, its value is overwritten. If it does not exist, it is added.

add

Headers to append. If the header already exists, the new value is added as an additional header line (preserving the original).

remove

Header names to remove. Matching is case-insensitive. If the header does not exist, the entry is silently ignored.

---

BlockResponse

Custom HTTP response returned to the client when a rule blocks a request.

When omitted from a "block" rule, a default 403 Forbidden response with an empty body is sent.

blockResponse {
  status = 451
  body = "Blocked by policy"
}

body

Response body text sent to the client. When null, an empty body is returned.

contentType

Value of the Content-Type response header. Default: "text/plain; charset=utf-8".

---

ProxyRule

A proxy rule that pairs match conditions with an action and optional transformations. Rules are defined inside ProxyConfig.rules and evaluated in declaration order.

new {
  label = "Block ad trackers"
  match = "*.doubleclick.net"
  action = "block"
}

match

Conditions that select which requests this rule applies to. Accepts either a hostname glob string (shorthand) or a full ProxyMatch object for multi-dimensional matching.

match = "*.ads.example.com"
match { host = "api.stripe.com"; path = "/v1/**" }

action

Action to take on matched requests. See RuleAction for the full list of actions. Default: "allow".

blockResponse

Custom HTTP response returned when action is "block". Ignored for other actions. When omitted, a default 403 Forbidden with an empty body is sent. See BlockResponse for customization options.

requestHeaders

Header mutations applied to the outgoing request before it is forwarded upstream. Only effective for "allow", "record", and "modify" actions — ignored for "block". See HeaderOps for set/add/remove operations.

responseHeaders

Header mutations applied to the upstream response before it is returned to the client. Ignored for "block" actions. See HeaderOps for set/add/remove operations.

mitm

Per-rule override for the global MITM interception setting (see MitmConfig). true forces MITM for matching HTTPS requests even if the host is globally excluded. false disables MITM even if globally included. null (default) inherits the global setting.

label

Human-readable label for this rule, displayed in the inspector UI and emitted in log messages. Has no effect on rule evaluation.

---