Configuration

iron-proxy is configured via a single YAML file, passed at startup with the -config flag:

iron-proxy -config /etc/iron-proxy/proxy.yaml

Below is a complete reference for every configuration option.

Full Example

dns:
  listen: ":53"
  proxy_ip: "172.20.0.2"
  upstream_resolver: "8.8.8.8:53"
  passthrough:
    - "*.internal.corp"
  records:
    - name: "custom.local"
      type: A
      value: "10.0.0.5"
 
proxy:
  http_listen: ":80"
  https_listen: ":443"
  tunnel_listen: ":1080"
  max_request_body_bytes: 1048576
  max_response_body_bytes: 0
 
tls:
  ca_cert: "/certs/ca.crt"
  ca_key: "/certs/ca.key"
  cert_cache_size: 1000
  leaf_cert_expiry_hours: 72
 
transforms:
  - name: allowlist
    config:
      domains:
        - "registry.npmjs.org"
      cidrs:
        - "10.0.0.0/8"
      rules:
        - host: "api.openai.com"
          methods: ["POST"]
          paths: ["/v1/*"]
        - host: "*.anthropic.com"
          methods: ["POST"]
          paths: ["/v1/messages", "/v1/complete"]
 
  - name: secrets
    config:
      source: env
      secrets:
        - var: OPENAI_API_KEY
          proxy_value: "proxy-openai-abc123"
          match_headers: ["Authorization"]
          match_body: false
          require: true
          hosts:
            - name: "api.openai.com"
 
  - name: grpc
    config:
      name: "policy-engine"
      target: "localhost:9500"
      send_request_body: true
      send_response_body: true
      rules:
        - host: "api.openai.com"
          methods: ["POST"]
          paths: ["/v1/*"]
      tls:
        enabled: true
        ca_cert: "/etc/iron-proxy/grpc-ca.pem"
        cert: "/etc/iron-proxy/grpc-client.pem"
        key: "/etc/iron-proxy/grpc-client-key.pem"
 
metrics:
  listen: ":9090"
 
log:
  level: "info"

dns

Configures the built-in DNS server. The DNS server returns proxy_ip for all lookups so that outbound traffic routes through the proxy.

dns.records[]

proxy

Configures the HTTP/HTTPS proxy listeners.

tls

Configures TLS interception. iron-proxy uses the provided CA certificate to mint leaf certificates on the fly for each upstream host.

transforms

An ordered array of transforms that run on every request. All transforms must pass for the request to be forwarded upstream. Transforms execute in the order they appear in the configuration.

Each transform has a name and a config object. The available transforms are documented below.

allowlist

Controls which destinations are reachable through the proxy. Requests to destinations not in the allowlist receive an HTTP 403 response.

There are two ways to specify allowed destinations: flat lists (domains and cidrs) that allow all methods and paths, and rules that support method and path restrictions. Both can be used together in the same allowlist.

allowlist.rules[]

Each rule matches a single host or CIDR, with optional method and path filters. A request is allowed if it matches any rule (or any flat domains/cidrs entry).

secrets

Swaps proxy tokens for real secret values at the egress boundary. Real secrets are never exposed to the sandboxed environment. Query parameters are always scanned for proxy tokens.

secrets.secrets[]

secrets.secrets[].hosts[]

Each host entry can specify a hostname pattern or a CIDR range, but not both.

grpc

Delegates request and response processing to an external gRPC server implementing the TransformService API. You can define multiple grpc transforms to pipeline through several servers.

grpc.tls

metrics

Configures the OpenTelemetry/Prometheus metrics endpoint.

log

Configures logging output.

OpenTelemetry Environment Variables

OTEL log export is configured through environment variables, not the YAML config file. Set OTEL_EXPORTER_OTLP_ENDPOINT to enable it. See the OTEL export guide for usage examples.