Listeners

Configure how agentgateway accepts and classifies incoming connections on a port.

Listeners sit inside a bind and describe how agentgateway handles incoming connections on that port. A listener can match traffic by hostname, specify the protocol, configure TLS termination, and group related routes.

Fields

binds[].listeners[].name · string

A human-readable name for this listener. Used in logs and metrics to identify the listener. Not required, but recommended for complex configurations with multiple listeners.

binds[].listeners[].namespace · string

The namespace this listener belongs to. Used when agentgateway is managed by a control plane (XDS) to scope resources. For local configurations, this can generally be omitted.

binds[].listeners[].hostname · string

The hostname this listener matches. Incoming requests are matched against this value using the HTTP Host header (or SNI for TLS connections).

Accepts wildcard prefixes: "*.example.com" matches api.example.com and admin.example.com, but not example.com.

When omitted, the listener matches all hostnames not claimed by another listener on the same port.

binds[].listeners[].protocol · string

The protocol to expect on this listener. Accepted values:

• HTTP — Plain HTTP/1.1 or HTTP/2 cleartext.
• HTTPS — HTTP over TLS. Requires tls to be configured.

When omitted, agentgateway infers the protocol from the traffic. For MCP and A2A backends, HTTP is the typical choice.

binds[].listeners[].tls · object

TLS configuration for this listener. Required when protocol is HTTPS. Agentgateway terminates TLS and forwards plaintext to the upstream backend.

Show tls fields

binds[].listeners[].tls.cert · string · required

Path to the PEM-encoded TLS certificate file (or the certificate contents inline).

binds[].listeners[].tls.key · string · required

Path to the PEM-encoded private key file (or the key contents inline).

binds[].listeners[].tls.root · string

Path to the PEM-encoded CA certificate bundle used to verify client certificates (mTLS). When omitted, client certificate verification is disabled.

binds[].listeners[].tls.cipherSuites · string[]

Optional allowlist of TLS cipher suites. Order is preserved — the first mutually supported suite is used. When omitted, the platform default cipher suites apply.

Example values: TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256.

binds[].listeners[].tls.minTLSVersion · string

Minimum TLS version to accept. Only TLSv1_2 and TLSv1_3 are supported. Defaults to TLSv1_2.

binds[].listeners[].tls.maxTLSVersion · string

Maximum TLS version to accept. Only TLSv1_2 and TLSv1_3 are supported. When omitted, no upper bound is enforced.

binds[].listeners[].routes · array

The list of routes this listener forwards traffic to. Routes are evaluated in order; the first match wins.

See Routes for the full field reference.

Examples

Plain HTTP listener

binds:
  - port: 8080
    listeners:
      - protocol: HTTP
        routes:
          - backends:
              - host: 127.0.0.1:9090

HTTPS listener with TLS termination

binds:
  - port: 8443
    listeners:
      - protocol: HTTPS
        tls:
          cert: /etc/certs/server.crt
          key: /etc/certs/server.key
        routes:
          - backends:
              - host: 127.0.0.1:9090

Mutual TLS (mTLS)

Supply a root CA to require and verify client certificates.

binds:
  - port: 8443
    listeners:
      - protocol: HTTPS
        tls:
          cert: /etc/certs/server.crt
          key: /etc/certs/server.key
          root: /etc/certs/ca.crt
        routes:
          - backends:
              - host: 127.0.0.1:9090

TLS with restricted cipher suites and version

binds:
  - port: 8443
    listeners:
      - protocol: HTTPS
        tls:
          cert: /etc/certs/server.crt
          key: /etc/certs/server.key
          minTLSVersion: TLSv1_3
          maxTLSVersion: TLSv1_3
          cipherSuites:
            - TLS_AES_128_GCM_SHA256
            - TLS_AES_256_GCM_SHA384
        routes:
          - backends:
              - host: 127.0.0.1:9090

Wildcard hostname matching

Use wildcard hostnames to capture all subdomains with one listener.

binds:
  - port: 8080
    listeners:
      # Handles api.example.com, admin.example.com, etc.
      - hostname: "*.example.com"
        routes:
          - backends:
              - host: internal-service:8080
      # Fallback: any other hostname
      - hostname: "*"
        routes:
          - policies:
              directResponse:
                status: 421
                body: "no listener matched"

Named listeners for observability

Naming listeners makes them easier to identify in logs and distributed traces.

binds:
  - port: 3000
    listeners:
      - name: mcp-listener
        namespace: production
        routes:
          - backends:
              - mcp:
                  targets:
                    - name: tools
                      stdio:
                        cmd: npx
                        args: ["@modelcontextprotocol/server-everything"]

Hostname matching precedence

When multiple listeners exist on the same port, agentgateway selects the most specific match:

1. Exact hostname match (e.g., api.example.com)
2. Wildcard prefix match (e.g., *.example.com)
3. Global wildcard (*) or no hostname specified

If two listeners share the same hostname on the same port, the behavior is undefined. Ensure each listener on a port has a distinct hostname.