For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Listeners

Configure listeners for agentgateway.

Listeners are the entrypoints for traffic into agentgateway. Agentgateway supports both HTTPHTTP (Hypertext Transfer Protocol)The protocol used for transmitting web pages and data over the internet. Agentgateway primarily handles HTTP and HTTPS traffic. and TCPTCP (Transmission Control Protocol)A connection-oriented protocol that provides reliable, ordered delivery of data. Agentgateway supports TCP listeners for non-HTTP traffic. traffic, with and without TLSTLS (Transport Layer Security)A cryptographic protocol that provides secure communication over a network. Agentgateway supports TLS for both incoming connections (listeners) and outgoing connections (backends)..

The following examples use routing-based configuration with binds. If you only route to LLM or MCP backends, the simplified llm and mcp modes set the listener port and TLS directly through llm.port, llm.tls, and mcp.port. For more information about the configuration styles, see Routing-based configuration.

HTTP Listeners

An HTTP listener can be configured by setting protocol: HTTP in the listener configuration. This is also the default protocol if no protocol is specified.

For example:

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 3000
  listeners:
  - protocol: HTTP
    routes: []

HTTPS Listeners

Serving HTTPSHTTPS (HTTP Secure)HTTP over TLS/SSL, providing encrypted communication. Agentgateway supports HTTPS listeners with TLS certificate configuration. traffic requires TLS certificates and setting protocol: HTTPS in the listener configuration:

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 443
  listeners:
  - protocol: HTTPS
    tls:
      cert: examples/tls/certs/cert.pem
      key: examples/tls/certs/key.pem
    routes: []

To generate a self-signed certificate for local testing, you can use openssl. Self-signed certificates trigger security warnings in browsers and clients, so use a certificate from a trusted certificate authority, such as Let’s Encrypt, in production.

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"

By default, a listener will match any traffic on the port. Requests can be routed based on the hostname using the hostname field. The most exact match will be used, as well as the corresponding TLS certificates.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 443
  listeners:
  - name: discrete
    protocol: HTTPS
    hostname: a.example.com
    tls:
      cert: examples/tls/certs/cert-a.pem
      key: examples/tls/certs/key-a.pem
    routes: []
  - name: wildcard
    protocol: HTTPS
    hostname: "*.example.com"
    tls:
      cert: examples/tls/certs/cert-wildcard.pem
      key: examples/tls/certs/key-wildcard.pem
    routes: []

Redirect HTTP to HTTPS

To serve both HTTP and HTTPS, configure an HTTP listener that redirects all traffic to the HTTPS listener with a requestRedirect policy. The following example listens for plaintext HTTP on port 80 and redirects it to HTTPS, while serving encrypted traffic on port 443.

binds:
- port: 80
  listeners:
  - name: http
    protocol: HTTP
    routes:
    - policies:
        requestRedirect:
          scheme: https
- port: 443
  listeners:
  - name: https
    protocol: HTTPS
    tls:
      cert: ./certs/cert.pem
      key: ./certs/key.pem
    routes: []

TCP Listeners

TCP listeners can be configured by setting protocol: TCP in the listener configuration. TCP listeners are useful when serving traffic that is not HTTP based.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 9000
  listeners:
  - name: default
    protocol: TCP
    tcpRoutes: []

Additionally, note the use of tcpRoutes instead of routes (which are HTTP routes) in the example.

Auto-detect protocol

Set protocol: auto to automatically detect the protocol for each incoming connection. The gateway peeks at the first byte of the connection. If the byte is 0x16 (a TLS ClientHello), the gateway dispatches the connection as TLS. Otherwise, the gateway dispatches it as HTTP. Use auto-detection in mixed-protocol environments where the same port accepts both TLS and plaintext traffic.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 443
  listeners:
  - protocol: auto
    routes: []
    tls:
      cert: examples/tls/certs/cert.pem
      key: examples/tls/certs/key.pem

TLS Listeners

For serving TLS traffic, the protocol: TLS can be used.

TLS listeners can either terminate or passthrough TLS traffic. While both a TCP and TLS passthrough listener do not terminate TLS, the latter enables the use of routing based on the hostname (utilizing SNI).

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 8443
  listeners:
  - hostname: passthrough.example.com
    protocol: TLS
    tcpRoutes: []
  - hostname: termination.example.com
    protocol: TLS
    tcpRoutes: []
    tls:
      cert: examples/tls/certs/cert.pem
      key: examples/tls/certs/key.pem