Binds

Configure the TCP ports agentgateway listens on and the listeners attached to each port.

The binds array is the top-level configuration that defines which TCP ports agentgateway listens on. Each bind maps a port number to one or more listeners, which in turn contain routes and backends.

Every valid agentgateway configuration must have at least one bind with at least one listener.

Structure

binds:
  - port: 3000
    listeners:
      - routes:
          - backends:
              - host: localhost:8080

The hierarchy flows as: bind (port) → listeners → routes → backends.

Fields

binds · array · required

Array of bind configurations. Each entry opens a listening TCP socket on the specified port.

binds[].port · number · required

The TCP port to listen on. agentgateway binds to 0.0.0.0 on this port, accepting connections on all available network interfaces.

Common values: 3000 (development), 8080 (HTTP proxy), 8443 (HTTPS proxy).

binds[].listeners · array · required

Array of listener configurations attached to this port. Each listener can match traffic by hostname or protocol and apply a distinct set of routes.

See Listeners for the full field reference.

Examples

Single port, single listener

The minimal configuration — one port, one listener, and one route.

basic/config.yaml

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

Multiple ports

Serve different protocols on separate ports by defining multiple binds.

multi-port

binds:
  # MCP proxy on port 3000
  - port: 3000
    listeners:
      - routes:
          - backends:
              - mcp:
                  targets:
                    - name: everything
                      stdio:
                        cmd: npx
                        args: ["@modelcontextprotocol/server-everything"]

  # HTTP proxy on port 8080
  - port: 8080
    listeners:
      - protocol: HTTP
        routes:
          - backends:
              - host: 127.0.0.1:9090

  # HTTPS with TLS termination on port 8443
  - port: 8443
    listeners:
      - protocol: HTTPS
        tls:
          cert: /etc/certs/tls.crt
          key: /etc/certs/tls.key
        routes:
          - backends:
              - host: 127.0.0.1:9090

Multiple listeners on one port

Multiple listeners on the same port can route traffic by hostname.

vhost

binds:
  - port: 8080
    listeners:
      - hostname: api.example.com
        routes:
          - backends:
              - host: api-backend:9000
      - hostname: admin.example.com
        routes:
          - backends:
              - host: admin-backend:9001
      - hostname: "*"
        routes:
          - policies:
              directResponse:
                status: 404
                body: "not found"

How binds map to network interfaces

agentgateway listens on all available network interfaces (0.0.0.0) for the configured port. To restrict to a specific interface, use a network policy at the operating system level or deploy agentgateway behind a load balancer that restricts source addresses.

Each bind is independent. Opening port 3000 and port 8080 creates two separate TCP listeners. Connections on port 3000 are never mixed with connections on port 8080.

For IPv6 support, set config.enableIpv6: true in the static configuration. When enabled, agentgateway also binds to [::] in addition to 0.0.0.0.