TLS

Reference for TLS configuration — listener TLS termination and backend TLS origination.

Agentgateway supports TLS in two directions:

• Listener TLS (tls) — TLS termination on the inbound listener. Clients connect over HTTPS/TLS.
• Backend TLS (backendTLS) — TLS origination when connecting to upstream backends. Agentgateway establishes encrypted connections to backends.

Only TLS 1.2 and 1.3 are supported.

Listener TLS

Listener TLS is configured on binds[].listeners[]:

binds:
- port: 3000
  listeners:
  - name: default
    protocol: HTTPS
    tls:
      cert: examples/tls/certs/cert.pem
      key: examples/tls/certs/key.pem

tls · object

TLS configuration for the listener.

Show tls fields

tls.cert · string · required

Path to the PEM-encoded TLS certificate file. The path is relative to the directory from which the Agentgateway binary runs.

tls:
  cert: examples/tls/certs/cert.pem

tls.key · string · required

Path to the PEM-encoded private key file.

tls:
  key: examples/tls/certs/key.pem

tls.root · string

Path to the PEM-encoded CA certificate bundle used for client certificate verification (mTLS). When set, Agentgateway requests and validates client certificates.

tls:
  root: examples/tls/certs/ca.pem

tls.cipherSuites · string[]

Optional allowlist of TLS cipher suites. The order in which ciphers are listed is preserved. When omitted, the default cipher suite selection applies.

tls:
  cipherSuites:
  - TLS_AES_128_GCM_SHA256
  - TLS_AES_256_GCM_SHA384

tls.minTLSVersion · string

Minimum TLS version to accept. Only 1.2 and 1.3 are supported.

tls:
  minTLSVersion: "1.2"

tls.maxTLSVersion · string

Maximum TLS version to accept. Only 1.2 and 1.3 are supported.

tls:
  maxTLSVersion: "1.3"

Backend TLS

Backend TLS is configured under binds[].listeners[].routes[].policies:

binds:
- port: 3000
  listeners:
  - routes:
    - policies:
        backendTLS:
          hostname: backend.example.com
          root: /etc/ssl/certs/ca-certificates.crt

backendTLS · object

TLS configuration for connections to upstream backends.

Show backendTLS fields

backendTLS.cert · string

Path to the PEM-encoded client certificate file used for mutual TLS (mTLS) with the backend.

backendTLS:
  cert: /etc/ssl/client.crt

backendTLS.key · string

Path to the PEM-encoded private key for the client certificate.

backendTLS:
  key: /etc/ssl/client.key

backendTLS.root · string

Path to the PEM-encoded CA certificate bundle used to verify the backend’s certificate.

backendTLS:
  root: /etc/ssl/certs/ca-certificates.crt

backendTLS.hostname · string

Override the Server Name Indication (SNI) hostname sent to the backend. When omitted, the backend’s hostname is used.

backendTLS:
  hostname: backend.internal.example.com

backendTLS.insecure · boolean

When true, Agentgateway skips all certificate verification for the backend connection. Not recommended for production.

backendTLS:
  insecure: true

backendTLS.insecureHost · boolean

When true, Agentgateway skips hostname verification but still validates the certificate chain.

backendTLS:
  insecureHost: true

backendTLS.alpn · string[]

Application-Layer Protocol Negotiation (ALPN) protocols to advertise during the TLS handshake.

backendTLS:
  alpn:
  - h2
  - http/1.1

backendTLS.subjectAltNames · string[]

List of acceptable Subject Alternative Names (SANs) in the backend’s certificate. When set, Agentgateway verifies that the backend certificate contains at least one of these SANs.

backendTLS:
  subjectAltNames:
  - backend.example.com
  - backend-alt.example.com

Examples

HTTPS listener with TLS 1.3 only

binds:
- port: 443
  listeners:
  - name: secure
    protocol: HTTPS
    tls:
      cert: /etc/ssl/certs/server.crt
      key: /etc/ssl/private/server.key
      minTLSVersion: "1.3"
      maxTLSVersion: "1.3"
    routes:
    - backends:
      - mcp:
          targets:
          - name: everything
            stdio:
              cmd: npx
              args: ["@modelcontextprotocol/server-everything"]

Mutual TLS listener

binds:
- port: 443
  listeners:
  - name: mtls
    protocol: HTTPS
    tls:
      cert: /etc/ssl/certs/server.crt
      key: /etc/ssl/private/server.key
      root: /etc/ssl/certs/ca.pem

Backend with mTLS

binds:
- port: 3000
  listeners:
  - routes:
    - policies:
        backendTLS:
          cert: /etc/ssl/client.crt
          key: /etc/ssl/client.key
          root: /etc/ssl/certs/backend-ca.pem
          hostname: backend.example.com
          alpn:
          - h2
      backends:
      - host: https://backend.example.com

Setting insecure: true disables all certificate verification. Only use this for local development or in fully trusted private networks. Never use it in production environments.

Listener TLS requires setting the protocol field on the listener to HTTPS. Routes under that listener will receive decrypted traffic.