Build the gateway with AI policies¶

After writing a custom AI policy, build it into the AI Gateway image so it can run alongside the built-in guardrails and rate-limiting policies.

Install the ap CLI¶

The ap CLI builds a custom gateway image that carries your own policies. It's the same ap CLI that AI Workspace CI/CD uses for commands such as ap gateway apply and ap ai-workspace build. If you already have it installed for that workflow, skip ahead to Configure the build file. Otherwise, download the binary for your platform from the AP CLI releases page and follow the steps below to install it.

macOS / LinuxWindows

Step 1: Extract the binary

After downloading the zip file for your platform, extract it:

unzip ap-darwin-amd64-v0.7.0.zip   # replace with your downloaded filename

Step 2: Move the binary to a bin directory

mkdir -p ~/bin
mv ap ~/bin/

Step 3: Add to PATH

Add the following line to your ~/.zshrc or ~/.bashrc:

export PATH="$HOME/bin:$PATH"

Step 4: Reload your shell

source ~/.zshrc   # or source ~/.bashrc

Step 5: Verify the installation

ap --version

Step 1: Extract the binary

After downloading the zip file, right-click it and select Extract All, or run in PowerShell:

Expand-Archive -Path ap-windows-amd64.zip -DestinationPath ap-windows-amd64

Step 2: Move the binary to a bin directory

New-Item -ItemType Directory -Force -Path "$HOME\bin"
Move-Item ap-windows-amd64\ap.exe "$HOME\bin\ap.exe"

Step 3: Add to PATH

Run the following in PowerShell to permanently add ~/bin to your user PATH:

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$HOME\bin", "User")

Step 4: Reload your shell

Close and reopen PowerShell for the PATH change to take effect.

Step 5: Verify the installation

ap --version

Configure the build file¶

The build.yaml file is included in the AI Gateway package you downloaded when setting up the AI Gateway. It declares the gateway version and the list of policies to include. Edit this file to add your custom AI policies before building the gateway image.

Sample custom policies

WSO2 provides sample custom policies, including AI-specific examples, in the api-platform sample policies repository.

Structure¶

version: v1
gateway:
  version: 1.2.0-beta
policies:
  - name: <policy-name>
    gomodule: <go-module-path>@<version>   # for policy hub managed policies
  - name: <custom-ai-policy-name>
    filePath: <relative-path-to-policy-dir> # for custom AI policies

Each policy entry uses one of two source types:

Field	Description
`gomodule`	The Go module reference for a Policy Hub managed policy, for example `github.com/wso2/gateway-controllers/policies/pii-masking@v1`
`filePath`	The path from `build.yaml` to a local custom AI policy directory

Add a custom AI policy¶

Your custom AI policy can reside anywhere on the filesystem. Use a relative path from the build.yaml file to point to it.

For example, if your directory layout is:

parent-directory/
├── my-ai-gateway/
│   └── build.yaml
└── my-ai-policy/          # policy lives outside the gateway directory
    ├── policy-definition.yaml
    └── myaipolicy.go

Add the policy to build.yaml using a relative filePath:

policies:
  - name: my-ai-policy
    filePath: ../my-ai-policy

Note

The path in filePath is always relative to the location of build.yaml, not the directory from which you run the ap command.

Build the gateway image¶

Once build.yaml is ready, run the following command from the directory containing build.yaml to build the custom gateway image:

ap gateway image build

This packages the gateway runtime together with every listed policy, built-in and custom, into a container image you use in place of the standard AI Gateway image.

Once the build completes, the output lists the two image names produced. For example:

✓ Built gateway images with 1 policies:
  • ghcr.io/wso2/api-platform/wso2apip-ai-gateway-1.2.0-beta-gateway-runtime:1.2.0-beta
  • ghcr.io/wso2/api-platform/wso2apip-ai-gateway-1.2.0-beta-gateway-controller:1.2.0-beta

A build-manifest.yaml file is also written alongside build.yaml, recording the resolved versions of all policies included in the build.

Update the Docker Compose file¶

After building, update the image: fields in your docker-compose.yaml to use the newly built images.

Locate the gateway-controller and gateway-runtime services and replace their image: values with the images from the build output:

services:
  gateway-controller:
    image: ghcr.io/wso2/api-platform/wso2apip-ai-gateway-1.2.0-beta-gateway-controller:1.2.0-beta  # (1)

  gateway-runtime:
    image: ghcr.io/wso2/api-platform/wso2apip-ai-gateway-1.2.0-beta-gateway-runtime:1.2.0-beta     # (2)

Replace with the gateway-controller image name from your build output.
Replace with the gateway-runtime image name from your build output.

Once updated, start the gateway as usual. api-platform.env continues to be loaded automatically via the Compose env_file: directive:

docker compose up

Next steps¶

Apply AI policies to proxies: sync your custom AI policy to the organization and apply it to LLM providers, App LLM proxies, and MCP proxies