AI Gateway

AI Gateway Source Control

An AI Gateway is a Zuplo project configured for AI traffic. A new project deploys automatically, so you can configure providers, pools, and apps without connecting a Git repository. Connect one when you want to write custom policies, review gateway changes in Git, or deploy from your own CI/CD.

The repository contains the gateway's routes and policy declarations. Custom policies are plain TypeScript files you commit alongside them.

Connect a repository

Zuplo supports GitHub, GitLab, Bitbucket, and Azure DevOps—see Source Control and Deployment for what each provider supports.

Open Settings → Source Control and choose one of the following:

Create New Repo starts a new repository with the name prefilled. With GitHub, this opens GitHub directly; create the repository, then return to the portal to connect it.
Connect an existing repository. Use an empty one so the gateway's source has the repository to itself.

When you connect, Zuplo adds the gateway's source to the repository and pushes it. The first push rebuilds production from that source. After that, with GitHub, pushes to your default branch deploy to production.

Until you connect a repository, production runs the gateway template Zuplo deploys at project creation, and Zuplo redeploys it daily from the latest template, so new routes and policies reach the gateway automatically. Connecting a repository doesn't replace that production URL; the first source deploy reuses it.

Connected gateways stop receiving template updates

Connecting a repository copies the current template into it. After that, production runs only what's in your repository, and Zuplo doesn't change it. Routes and policies that Zuplo later adds to the template, such as the /u/ route that serves the User App, don't reach the gateway until you add them. See Keep the gateway up to date.

To work with the source locally, clone the repository:

Code
git clone https://github.com/GITHUB_ORG/REPO_NAME.git

Replace GITHUB_ORG with your GitHub organization or user, and REPO_NAME with the repository name.

If your default branch requires pull requests, Zuplo pushes the gateway source to a setup branch and surfaces a pull request for you to merge. The project finishes connecting once the pull request lands on the default branch.

What the repository contains

The scaffolded gateway is a small, readable Zuplo project:

File	Purpose
`config/ai.oas.json`	The gateway's route, which the AI Gateway handler serves
`config/policies.json`	The menu of policies apps can add to their policy chains
`zuplo.jsonc`	Project configuration
`env.example`	Example environment variables
`tsconfig.json`	TypeScript configuration for custom policy modules

Add custom policy modules under modules/ and declare them in config/policies.json—see Custom Policies.

How deployments work

After you connect a repository, its default branch is what production runs. With GitHub, every push to it deploys automatically. With GitLab, Bitbucket, and Azure DevOps, your own CI/CD pipeline deploys by calling zuplo deploy—see Source Control and Deployment.

After you connect, the Code tab opens the gateway's source. You can also clone the repository and edit it with your normal tools.

Three categories of changes take effect differently:

Change	Takes effect
Repository changes (routes, `policies.json`, custom policy code)	On the next deploy of the default branch
App policy chains, pools, budgets, and templates (portal changes)	Within about a minute, no deploy needed
Provider settings and environment variables	Automatically, via a rebuild and deploy Zuplo starts

Provider API keys are stored as environment variables, so saving provider settings or environment variables triggers an automatic production deployment.

Keep the gateway up to date

When Zuplo adds routes or policies to the AI Gateway template, a connected gateway doesn't get them until you add them to config/ai.oas.json and config/policies.json. The zuplo source upgrade command adds the missing definitions for you. Run it from a local clone of the repository:

Install the latest zuplo package. If package.json or the lockfile change, commit them; applying an upgrade requires a clean working tree.
```
Code
npm install zuplo@latest
```
Preview the upgrade. The CLI prints each missing route and policy and a diff, without changing any files:
```
Code
npx zuplo source upgrade --type ai-gateway
```
Apply the upgrade. The CLI asks you to confirm before it writes the files:
```
Code
npx zuplo source upgrade --type ai-gateway --apply
```
Review and test the changes, then commit and push them:
```
Code
git add --all
git commit -m "Upgrade AI Gateway template"
git push
```
The push deploys like any other repository change—see How deployments work.

The command only adds what's missing. It doesn't change your existing routes, policies, or custom policy code. If an addition conflicts with your configuration or can't be verified, the CLI changes nothing and prints the definitions so you can add them by hand. Review authentication and policy order before you add a route manually.

Next steps

Policy Chains: how apps select policies from config/policies.json
Custom Policies: add your own policy to the repository
zuplo source upgrade: every option and the recovery steps for an interrupted upgrade

Edit this page

Last modified on October 7, 2026

Getting Started Universal API