# AI Gateway Configuration Loader Policy

:::note{title="AI Gateway Policy"}

This policy is for use with the [AI Gateway](/docs/ai-gateway/introduction). See
the AI Gateway documentation to learn how to configure and govern AI models
with Zuplo.

:::

The AI Gateway Configuration Loader loads each application's configuration into
the request-scoped channel — reusing the channel from route-level
`ai-gateway-auth-v2-inbound` when present, otherwise fetching by path `app_id`.
It does not run the application's policy chain; place
`ai-gateway-configuration-executor-v2-inbound` after it for that. When this
loader is omitted, the executor still loads configuration itself.

## Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

```json title="config/policies.json"
{
  "name": "my-ai-gateway-configuration-loader-v2-inbound-policy",
  "policyType": "ai-gateway-configuration-loader-v2-inbound",
  "handler": {
    "export": "AIGatewayConfigurationLoaderV2InboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "cacheTtlSeconds": 10
    }
  }
}
```

### Policy Configuration

- `name` <code className="text-green-600">&lt;string&gt;</code> - The name of your policy instance. This is used as a reference in your routes.
- `policyType` <code className="text-green-600">&lt;string&gt;</code> - The identifier of the policy. This is used by the Zuplo UI. Value should be `ai-gateway-configuration-loader-v2-inbound`.
- `handler.export` <code className="text-green-600">&lt;string&gt;</code> - The name of the exported type. Value should be `AIGatewayConfigurationLoaderV2InboundPolicy`.
- `handler.module` <code className="text-green-600">&lt;string&gt;</code> - The module containing the policy. Value should be `$import(@zuplo/runtime)`.
- `handler.options` <code className="text-green-600">&lt;object&gt;</code> - The options for this policy. [See Policy Options](#policy-options) below.

### Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

- `cacheTtlSeconds` <code className="text-green-600">&lt;number&gt;</code> - The time in seconds to cache app configurations loaded by app_id. Defaults to 10 seconds when omitted. Higher values decrease latency; lower values pick up portal changes sooner. Cached results remain valid until the cache expires even if the configuration changes in the portal. When ai-gateway-auth-v2-inbound already loaded the configuration for the request, this cache is not used. Defaults to `10`.

## Using the Policy

# AI Gateway Configuration Loader

The AI Gateway Configuration Loader loads each application's configuration into
the request-scoped app-configuration channel. Configuration comes from
route-level `ai-gateway-auth-v2-inbound` when that policy already ran, otherwise
from the route's `app_id` path parameter via Gateway Service.

This policy does **not** run `inboundPolicyChain`. Pair it with
`ai-gateway-configuration-executor-v2-inbound` when applications select policies
dynamically. If you omit this loader, the executor still loads configuration
before running the chain.

Applications can still require API keys later by including
`ai-gateway-auth-v2-inbound` in their own `inboundPolicyChain`.

## Build an AI Gateway from scratch

### 1. Declare the policies

Add the loader, the executor, and every policy an application may select to
`config/policies.json`:

```json
{
  "policies": [
    {
      "name": "ai-gateway-configuration-loader-v2-inbound",
      "policyType": "ai-gateway-configuration-loader-v2",
      "handler": {
        "export": "AIGatewayConfigurationLoaderV2InboundPolicy",
        "module": "$import(@zuplo/runtime)",
        "options": {
          "cacheTtlSeconds": 60
        }
      }
    },
    {
      "name": "ai-gateway-configuration-executor-v2-inbound",
      "policyType": "ai-gateway-configuration-executor-v2",
      "handler": {
        "export": "AIGatewayConfigurationExecutorV2InboundPolicy",
        "module": "$import(@zuplo/runtime)",
        "options": {
          "cacheTtlSeconds": 60
        }
      }
    }
  ]
}
```

`cacheTtlSeconds` sets how long a loaded app configuration is cached by
`app_id`. It defaults to 10 seconds and accepts any value of 2 seconds or more —
raise it to cut Gateway Service calls, lower it to pick up portal changes
sooner. The AI Gateway project template ships 5 seconds.

Neither the loader nor the executor may appear in an application's
`inboundPolicyChain`. The executor rejects those entries fail-closed.

### 2. Add the loader and executor to the route

Place the loader before the executor on each AI Gateway route:

```json
{
  "x-zuplo-route": {
    "corsPolicy": "none",
    "handler": {
      "export": "aiGatewayHandlerV2",
      "module": "$import(@zuplo/runtime)",
      "options": {}
    },
    "policies": {
      "inbound": [
        "ai-gateway-configuration-loader-v2-inbound",
        "ai-gateway-configuration-executor-v2-inbound"
      ]
    }
  }
}
```

Authentication is optional and placement controls its scope:

- **App-level** — add `ai-gateway-auth-v2-inbound` to an application's
  `inboundPolicyChain`. Only that application requires an API key.
- **Route-level** — add `ai-gateway-auth-v2-inbound` on the route **before** the
  loader. That requires an API key for every application on the route.

### Executor-only routes

Routes that list only `ai-gateway-configuration-executor-v2-inbound` keep
working. The executor loads configuration when the channel is empty, then runs
the chain. Use the dedicated loader when you want other route policies between
load and chain execution, or a clearer separation of concerns.

## Configuration checklist

Before deploying:

1. Declare the loader (optional but recommended), the executor, and every
   selectable policy in `config/policies.json`.
2. Put the loader before the executor on every AI Gateway route — or put only
   the executor when you prefer the combined path.
3. Do not add the loader or executor to any application's `inboundPolicyChain`.

Read more about [how policies work](/articles/policies)