> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentgateway/agentgateway/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker

> Run Agentgateway with Docker or Docker Compose.

Agentgateway ships a minimal, production-ready container image built on the [Chainguard](https://chainguard.dev) `glibc-dynamic` base image. A `Dockerfile.windows` is also provided for Windows containers.

## Pre-built images

Pre-built images are published to the GitHub Container Registry:

```bash theme={null}
docker pull ghcr.io/agentgateway/agentgateway:latest
```

## Building the image

<Tabs>
  <Tab title="Linux / macOS">
    The default `Dockerfile` uses a multi-stage build. It builds the UI with Node, compiles the Rust binary (optionally with musl for a fully static binary), and copies only the final binary into the minimal runtime image.

    ```bash theme={null}
    make docker
    ```

    This is equivalent to:

    ```bash theme={null}
    docker build \
      --build-arg VERSION=$(git describe --tags --always --dirty) \
      --build-arg GIT_REVISION=$(git rev-parse HEAD) \
      -t ghcr.io/agentgateway/agentgateway:$(git describe --tags --always --dirty) \
      . --progress=plain
    ```
  </Tab>

  <Tab title="Linux (musl / static)">
    To build a fully statically-linked binary using musl, pass `BUILDER=musl`:

    ```bash theme={null}
    make docker-musl
    ```

    This sets `--build-arg BUILDER=musl` and targets `aarch64-unknown-linux-musl` or `x86_64-unknown-linux-musl` depending on the host architecture.
  </Tab>

  <Tab title="Windows">
    The `Dockerfile.windows` uses Windows Server Core as the builder and Nano Server as the runtime image:

    ```bash theme={null}
    make docker
    ```

    On Windows, `make docker` automatically selects `Dockerfile.windows`. The entrypoint is `C:\app\agentgateway.exe`.
  </Tab>
</Tabs>

## Dockerfile walkthrough

The Linux `Dockerfile` has four stages:

```dockerfile Dockerfile theme={null}
# syntax=docker/dockerfile:1.11
ARG BUILDER=base

# Stage 1: build the UI
FROM docker.io/library/node:23.11.0-bookworm AS node
WORKDIR /app
COPY ui .
RUN --mount=type=cache,target=/app/npm/cache npm install
RUN --mount=type=cache,target=/app/npm/cache npm run build

# Stage 2 (musl variant): install musl toolchain
FROM docker.io/library/rust:1.93.0-trixie AS musl-builder
# ... installs musl-tools and adds the musl Rust target

# Stage 2 (base variant): standard glibc build
FROM docker.io/library/rust:1.93.0-trixie AS base-builder

# Stage 3: compile the binary
FROM ${BUILDER}-builder AS builder
ARG PROFILE=release
WORKDIR /app
COPY Makefile Cargo.toml Cargo.lock ./
COPY --from=node /app/out ./ui/out
RUN cargo build --features ui --target "$(cat /build/target)" --profile ${PROFILE}

# Stage 4: minimal runtime image
FROM cgr.dev/chainguard/glibc-dynamic AS runner
COPY --from=builder /out/agentgateway /app/agentgateway
ENTRYPOINT ["/app/agentgateway"]
```

Key points:

* Build caches for `npm` and Cargo registries are mounted as `--mount=type=cache` to keep iterative builds fast.
* The runtime image is `cgr.dev/chainguard/glibc-dynamic` — a distroless image with no shell, minimal attack surface, and regular security updates.
* `VERSION` and `GIT_REVISION` build args are embedded in the binary. The build fails if version information is missing (the `--version` output must not contain `"unknown"`).

## Running with Docker

### Mount a configuration file

Pass your configuration file into the container as a bind mount and point the binary to it with `-f`:

```bash theme={null}
docker run \
  --rm \
  -p 8080:8080 \
  -p 15000:15000 \
  -v $(pwd)/config.yaml:/config.yaml:ro \
  ghcr.io/agentgateway/agentgateway:latest \
  -f /config.yaml
```

### Port mappings

| Port    | Purpose                                               |
| ------- | ----------------------------------------------------- |
| `8080`  | MCP / A2A listener (configurable in your config file) |
| `15000` | Admin UI (`http://localhost:15000/ui`)                |
| `15020` | Prometheus metrics (`/metrics`)                       |
| `15021` | Readiness probe (`/healthz/ready`)                    |

<Note>
  The listener port (default `8080`) is defined in your configuration file, not hard-coded. Adjust the `-p` flag to match whatever port you configure.
</Note>

### Volume mounts

| Path in container        | Purpose                                                       |
| ------------------------ | ------------------------------------------------------------- |
| `/config.yaml`           | Configuration file (mount as read-only)                       |
| `/certs/`                | TLS certificates referenced from your config                  |
| `/manifests/jwt/pub-key` | JWT public key (if using local JWKS as in the example config) |

## Environment variable configuration

You can override individual settings without modifying the config file by passing environment variables:

```bash theme={null}
docker run \
  --rm \
  -p 8080:8080 \
  -p 15000:15000 \
  -e DNS_EDNS0=true \
  -v $(pwd)/config.yaml:/config.yaml:ro \
  ghcr.io/agentgateway/agentgateway:latest \
  -f /config.yaml
```

## Docker Compose examples

### Agentgateway with telemetry

The repository includes a `docker-compose.yaml` in `examples/telemetry/` that adds Jaeger and an OpenTelemetry collector alongside Agentgateway:

```yaml examples/telemetry/docker-compose.yaml theme={null}
services:
  jaeger:
    container_name: jaeger
    restart: unless-stopped
    image: jaegertracing/all-in-one:latest
    ports:
    - "127.0.0.1:16686:16686"
    - "127.0.0.1:14268:14268"
    environment:
    - COLLECTOR_OTLP_ENABLED=true

  otel-collector:
    container_name: otel-collector
    image: otel/opentelemetry-collector-contrib:0.146.0
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml
    ports:
      - "127.0.0.1:4317:4317"
    depends_on:
      - jaeger
```

To run Agentgateway alongside these services, add a service entry pointing to the OTLP endpoint in your config:

```yaml config.yaml theme={null}
config:
  tracing:
    otlpEndpoint: "http://otel-collector:4317"
    otlpProtocol: grpc
    randomSampling: "0.1"
```

### Agentgateway with an OpenAPI backend

The `examples/openapi/docker-compose.yaml` shows a petstore backend service running alongside the gateway:

```yaml examples/openapi/docker-compose.yaml theme={null}
services:
  openapi-petstore:
    image: swaggerapi/petstore3:1.0.27
    ports:
    - "8080:8080"
```

## Health checks

Add a Docker health check so that container orchestrators can detect when Agentgateway is ready:

```yaml docker-compose.yaml theme={null}
services:
  agentgateway:
    image: ghcr.io/agentgateway/agentgateway:latest
    command: ["-f", "/config.yaml"]
    ports:
      - "8080:8080"
      - "15000:15000"
      - "15020:15020"
      - "15021:15021"
    volumes:
      - ./config.yaml:/config.yaml:ro
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:15021/healthz/ready"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 5s
```

<Warning>
  The Chainguard runtime image has no shell. Use `wget` or `curl` (if present) for health check commands, or prefer a TCP-based check. Do not use `sh -c` or bash-based health checks.
</Warning>

## Windows containers

A `Dockerfile.windows` is provided for environments that require native Windows containers. It uses Windows Server Core (`ltsc2022`) as the build image and Nano Server as the runtime:

```dockerfile Dockerfile.windows theme={null}
FROM mcr.microsoft.com/windows/servercore:ltsc2022 AS builder
# Installs Chocolatey, then: rust-ms protoc make nodejs cmake nasm
# Installs VS 2022 Build Tools with MSVC and Windows 11 SDK

FROM mcr.microsoft.com/windows/nanoserver:ltsc2022 AS runner
COPY --from=builder C:/out/agentgateway.exe C:/app/agentgateway.exe
ENTRYPOINT ["C:\\app\\agentgateway.exe"]
```

Build and run:

```powershell theme={null}
make docker   # selects Dockerfile.windows automatically on Windows

docker run --rm -p 8080:8080 -v ${PWD}/config.yaml:C:/config.yaml `
  ghcr.io/agentgateway/agentgateway:latest -f C:/config.yaml
```