Docker

Install and run agentgateway as a Docker container, on its own or with Docker Compose.

To run agentgateway as a container, follow the steps to start the container, verify that it runs, and open the UI. Agentgateway publishes the official images at cr.agentgateway.dev/agentgateway.

Run the container

Start the container

You can either mount a directory and let agentgateway create a configuration file in it, or mount a configuration file that you wrote yourself.

Mount a writable directory at the /config path. Agentgateway generates a default configuration in the config.yaml file in that directory on the first start, and creates a SQLite database alongside it.

mkdir agentgateway-config
docker run -d \
  --name agentgateway \
  --user "$(id -u):$(id -g)" \
  -v "$PWD/agentgateway-config:/config" \
  -p 4000:4000 \
  cr.agentgateway.dev/agentgateway:latest-dev

The --user flag lets the container read and write the mounted directory as your user. The generated configuration includes a SQLite database and serves the UI on the default gateway. The database stores LLM analytics, logs, and other runtime data. For details, see Database.

The generated configuration looks like this:

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
config:
  database:
    url: sqlite:///config/data.db
gateways:
  default:
    port: 4000
ui:
  gateways: default

Mount your configuration file and pass the file with -f. Include the database and UI settings, because supplied files receive no generated defaults.

Create a configuration file with the database and UI settings shown in this example.
The config.database.url field sets the SQLite file path. The ui.gateways field serves the UI on the default gateway. For a fuller starting point, add these settings to the example configuration file.
```
cat <<'EOF' > config.yaml
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
config:
  database:
    url: sqlite:///data/data.db
gateways:
  default:
    port: 4000
ui:
  gateways: default
EOF
```

Start the container with the configuration file and a writable /data directory for SQLite.

Keep the configuration mount writable to save UI changes. For database details, see Database.

mkdir -p data
docker run -d \
  --name agentgateway \
  --user "$(id -u):$(id -g)" \
  -v "$PWD/config.yaml:/config.yaml" \
  -v "$PWD/data:/data" \
  -p 4000:4000 \
  cr.agentgateway.dev/agentgateway:latest-dev \
  -f /config.yaml

For details about saving UI changes, see Configuration storage.

Important

The admin interface defaults to localhost:15000, which is the container’s own loopback interface, so publishing port 15000 does not make it reachable from your host. Reach the UI on a gateway port instead, as the generated configuration does. That is the supported path, and it is the only one that you can authenticate. For more information, see Reach the UI in a container.

Verify that the container runs

Check the status of the container.

docker ps --filter name=agentgateway

Example output:

CONTAINER ID   IMAGE                                         COMMAND               CREATED         STATUS         PORTS                                         NAMES
8bac1aad45ba   cr.agentgateway.dev/agentgateway:latest-dev   "/app/agentgateway"   5 seconds ago   Up 4 seconds   0.0.0.0:4000->4000/tcp, [::]:4000->4000/tcp   agentgateway

Find the UI address

Check the logs. Agentgateway logs which configuration file it loaded and where it serves the UI.

docker logs agentgateway

Example output:

info	state_manager	loaded config from File("/config/config.yaml")
info	state_manager	Watching config file: /config/config.yaml
info	app	serving UI at http://localhost:4000/ui
info	proxy::gateway	started bind	bind="bind/4000"

Open the UI

Open the address from the log output, such as http://localhost:4000/ui, to get started.

Run with Docker Compose

Docker Compose follows the same approach as the docker run command.

Create the Compose file

Create a compose.yaml file. The user value must be your own user and group IDs so that the container can write to the mounted directory.

services:
  agentgateway:
    container_name: agentgateway
    restart: unless-stopped
    image: cr.agentgateway.dev/agentgateway:latest-dev
    # Replace with your user and group IDs, such as the output of: id -u && id -g
    user: "1000:1000"
    ports:
      - "4000:4000"
    volumes:
      - ./agentgateway-config:/config

Start the service

Create the configuration directory and start the service. Agentgateway generates a configuration file in the directory on the first start.

mkdir agentgateway-config
docker compose up -d

Verify that the service runs

Check the status of the service.

docker compose ps

Example output:

NAME           IMAGE                                         COMMAND               SERVICE        CREATED         STATUS         PORTS
agentgateway   cr.agentgateway.dev/agentgateway:latest-dev   "/app/agentgateway"   agentgateway   9 seconds ago   Up 8 seconds   0.0.0.0:4000->4000/tcp, [::]:4000->4000/tcp

Open the UI

Open http://localhost:4000/ui to get started.

Cleanup

Stop and remove the container.

docker rm -f agentgateway

Agentgateway leaves the configuration file and the SQLite database in the mounted directory. If you do not want to keep them, remove the directory too.

Next steps

Set up the UI to open, expose, and secure the web interface.
Set up a database for the Analytics and Logs pages, and for API key budgets.
Choose where configuration is stored.
Update your configuration after the container is running.
Upgrade agentgateway to a new image tag.

Binary Helm

Was this page helpful?

Docker

Run the container

Start the container

Verify that the container runs

Find the UI address

Open the UI

Run with Docker Compose

Create the Compose file

Start the service

Verify that the service runs

Open the UI

Cleanup

Next steps

What could be improved?