Install the gateway¶
You can run the AI Gateway on your own machine, on a virtual machine, in Docker, or on Kubernetes. The first three share one installation procedure — download the distribution, run the setup script, and start the containers with Docker Compose — and this page carries that procedure in full. Kubernetes uses a Helm chart instead.
This page installs a gateway and starts it, and nothing else. For a walkthrough that also deploys an LLM provider and an LLM proxy and routes a request through them, see the quick start guide.
The commands below use version 1.2.0. Substitute the API Platform AI Gateway release version you want to run in the download URL, the archive name, and the directory name. The PowerShell commands require PowerShell 7.3 or later.
Install and start the gateway¶
Select the context you're installing in, then follow the steps in that tab.
Install on your own machine to evaluate the gateway or develop against it.
Prerequisites: a Docker-compatible container runtime with the Compose plugin, such as Docker Desktop, Podman, Rancher Desktop, Colima, or Docker Engine with the Compose plugin.
Step 1: Download the distribution
# Download distribution.
curl -fL -o wso2apip-ai-gateway-1.2.0.zip https://github.com/wso2/api-platform/releases/download/ai-gateway/v1.2.0/wso2apip-ai-gateway-1.2.0.zip
# Unzip the downloaded distribution.
unzip wso2apip-ai-gateway-1.2.0.zip
cd wso2apip-ai-gateway-1.2.0/
On Windows, download and unpack the distribution with PowerShell:
Invoke-WebRequest -Uri https://github.com/wso2/api-platform/releases/download/ai-gateway/v1.2.0/wso2apip-ai-gateway-1.2.0.zip -OutFile wso2apip-ai-gateway-1.2.0.zip
Expand-Archive -Path wso2apip-ai-gateway-1.2.0.zip -DestinationPath .
Set-Location wso2apip-ai-gateway-1.2.0
Step 2: Run the one-time setup
The setup script provisions the Advanced Encryption Standard (AES)-256 at-rest encryption key, the router HTTPS listener certificate, api-platform.env, and the gateway-controller admin credentials. It prints the admin password once — copy it.
On Windows, run the PowerShell setup script instead. It takes the same flags and provisions the same files:
Step 3: Export the admin credentials
Management API calls authenticate with these credentials. The username defaults to admin; use the password the setup script just printed.
On Windows, set them as PowerShell environment variables instead:
Step 4: Start the gateway and verify it answers
# Start the complete stack
docker compose up
# Verify gateway controller admin endpoint is running
curl http://localhost:9094/api/admin/v1/health
On Windows, the start command is the same, and the health check is curl.exe http://localhost:9094/api/admin/v1/health. Note the .exe, since curl is an alias for Invoke-WebRequest in Windows PowerShell. PowerShell 7 removes that alias, and curl.exe works in both versions.
Nothing extra applies here. The gateway runs standalone, and connecting it to a control plane is optional.
Install on a VM you administer, such as an EC2 instance or a managed VM.
Prerequisites: cURL, unzip, and a Docker-compatible container runtime with the Compose plugin on the host.
Step 1: Download the distribution
# Download distribution.
curl -fL -o wso2apip-ai-gateway-1.2.0.zip https://github.com/wso2/api-platform/releases/download/ai-gateway/v1.2.0/wso2apip-ai-gateway-1.2.0.zip
# Unzip the downloaded distribution.
unzip wso2apip-ai-gateway-1.2.0.zip
cd wso2apip-ai-gateway-1.2.0/
On Windows, download and unpack the distribution with PowerShell:
Invoke-WebRequest -Uri https://github.com/wso2/api-platform/releases/download/ai-gateway/v1.2.0/wso2apip-ai-gateway-1.2.0.zip -OutFile wso2apip-ai-gateway-1.2.0.zip
Expand-Archive -Path wso2apip-ai-gateway-1.2.0.zip -DestinationPath .
Set-Location wso2apip-ai-gateway-1.2.0
Step 2: Run the one-time setup
The setup script provisions the Advanced Encryption Standard (AES)-256 at-rest encryption key, the router HTTPS listener certificate, api-platform.env, and the gateway-controller admin credentials. It prints the admin password once — copy it.
On Windows, run the PowerShell setup script instead. It takes the same flags and provisions the same files:
Step 3: Export the admin credentials
Management API calls authenticate with these credentials. The username defaults to admin; use the password the setup script just printed.
On Windows, set them as PowerShell environment variables instead:
Step 4: Start the gateway and verify it answers
# Start the complete stack
docker compose up
# Verify gateway controller admin endpoint is running
curl http://localhost:9094/api/admin/v1/health
On Windows, the start command is the same, and the health check is curl.exe http://localhost:9094/api/admin/v1/health. Note the .exe, since curl is an alias for Invoke-WebRequest in Windows PowerShell. PowerShell 7 removes that alias, and curl.exe works in both versions.
Two things differ from a local install:
- Reachability. Clients reach the gateway over the VM's network address rather than
localhost, so open the router's listener ports on the VM and any firewall in front of it. For the ports involved, see Default ports. - Control plane registration. If the gateway reports to AI Workspace, add
APIP_GW_CONTROLLER_CONTROLPLANE_HOSTandAPIP_GW_CONTROLLER_CONTROLPLANE_TOKENtoapi-platform.envbefore Step 4. Both default to empty, which runs the gateway standalone. See Delivering environment values for how the file is loaded, and Connect the gateway to AI Workspace for obtaining the token.
Install with Docker Compose, on any host with a Docker-compatible runtime.
Prerequisites: cURL and unzip. The distribution ships a Compose file, and the setup script generates the environment file it reads.
Step 1: Download the distribution
# Download distribution.
curl -fL -o wso2apip-ai-gateway-1.2.0.zip https://github.com/wso2/api-platform/releases/download/ai-gateway/v1.2.0/wso2apip-ai-gateway-1.2.0.zip
# Unzip the downloaded distribution.
unzip wso2apip-ai-gateway-1.2.0.zip
cd wso2apip-ai-gateway-1.2.0/
On Windows, download and unpack the distribution with PowerShell:
Invoke-WebRequest -Uri https://github.com/wso2/api-platform/releases/download/ai-gateway/v1.2.0/wso2apip-ai-gateway-1.2.0.zip -OutFile wso2apip-ai-gateway-1.2.0.zip
Expand-Archive -Path wso2apip-ai-gateway-1.2.0.zip -DestinationPath .
Set-Location wso2apip-ai-gateway-1.2.0
Step 2: Run the one-time setup
The setup script provisions the Advanced Encryption Standard (AES)-256 at-rest encryption key, the router HTTPS listener certificate, api-platform.env, and the gateway-controller admin credentials. It prints the admin password once — copy it.
On Windows, run the PowerShell setup script instead. It takes the same flags and provisions the same files:
Step 3: Export the admin credentials
Management API calls authenticate with these credentials. The username defaults to admin; use the password the setup script just printed.
On Windows, set them as PowerShell environment variables instead:
Step 4: Start the gateway and verify it answers
# Start the complete stack
docker compose up
# Verify gateway controller admin endpoint is running
curl http://localhost:9094/api/admin/v1/health
On Windows, the start command is the same, and the health check is curl.exe http://localhost:9094/api/admin/v1/health. Note the .exe, since curl is an alias for Invoke-WebRequest in Windows PowerShell. PowerShell 7 removes that alias, and curl.exe works in both versions.
Beyond a local evaluation, two things apply:
- Control plane registration. Add the two
APIP_GW_CONTROLLER_CONTROLPLANE_*variables toapi-platform.envif the gateway reports to AI Workspace. See Connect the gateway to AI Workspace. - Persistence and secrets. The setup script generates the at-rest encryption key, the listener certificate, and the admin credentials once. Keep them with the deployment rather than regenerating them, and see Gateway configuration and environment interpolation for how the gateway reads them.
Installing on a Kubernetes cluster with Helm.
Kubernetes does not use the setup script or Docker Compose. A Helm chart renders the gateway's configuration into a ConfigMap and injects the encryption key, control plane token, and database password from Kubernetes Secrets, which you create before installing the chart.
There are two deployment modes — a standalone chart, and an operator that manages the gateway through custom resources. For the comparison and the procedure for each, see Kubernetes deployment modes.
For a replicated, high-availability installation, see Production deployment overview.
Resolve a port conflict¶
The Docker Compose installation binds ports 8080, 8443, 9090, and 9094 on the host. If the start command fails with a port binding error, identify what is already listening on those ports.
On macOS or Linux, run:
lsof -nP -iTCP:8080 -sTCP:LISTEN
lsof -nP -iTCP:8443 -sTCP:LISTEN
lsof -nP -iTCP:9090 -sTCP:LISTEN
lsof -nP -iTCP:9094 -sTCP:LISTEN
On Windows PowerShell, run:
Get-NetTCPConnection -State Listen -LocalPort 8080,8443,9090,9094 | Select-Object LocalAddress, LocalPort, OwningProcess
Stop the conflicting service if you don't need it. If you need to keep it running, change the host-side value of the relevant ports: mapping in docker-compose.yaml. Then use the remapped host port in the verification and test commands on this page.
Customize the configuration¶
The setup script (setup.sh, or setup.ps1 on Windows) writes api-platform.env, which is loaded into the containers via the Docker Compose env_file directive. To change the storage backend, connect to a control plane, or tune other settings, edit that file, or the config.toml interpolation tokens directly. See Gateway configuration and environment interpolation.
Next steps¶
- Connect an upstream LLM service: Create and configure an LLM provider
- Expose that provider to applications: Create and configure an LLM proxy
- Expose an MCP server through the gateway: MCP proxy
- Govern this gateway from the control plane: Connect the gateway to AI Workspace