# Managing Apps

An app represents one caller of your AI Gateway—a service, an agent, or a
feature in a larger codebase. Each app has its own API key, which the gateway
checks once you add the
[authentication policy](./policy-chains.mdx#authentication); usage is tracked
per app whether or not that policy applies. Each app belongs to a
[pool](./pools.mdx), which controls who can access and manage the app. Provider
access is governed separately by the user's Zuplo account and Zuplo project
roles. A Zuplo account contains one or more projects; this AI Gateway and its
providers, pools, and apps belong to one Zuplo project. See
[Role Permissions](../articles/accounts/roles-and-permissions.mdx).

:::note{title="App permissions"}

A pool **Admin** can create, edit, and delete apps owned by that pool. A pool
**Member** can access the pool's apps but can't manage them. Both roles require
permission to view the Zuplo project that contains the AI Gateway.

:::

## Creating an App

<Stepper>

1. Open the [Apps](https://portal.zuplo.com/+/account/project/ai/apps) tab of
   your AI Gateway project in the Zuplo Portal.

1. Select the pool that will own the app, then click **Create App** in the
   pool's header. You can also choose **New App** from the menu next to **New
   Pool** above the tree.

1. Enter the **App name**.

1. Confirm the **Pool**—it's prefilled with the pool you started from.

1. Click **Create app**

</Stepper>

That's the whole dialog. The portal then takes you to the app's **Policies**
tab. If the app's pool defines a [policy template](./policy-templates.mdx), the
new app starts with that chain; otherwise the chain is empty and the app is
subject to no app-specific controls until you add policies. Pool and gateway
usage limits still apply.

## Restricting models

By default an app isn't restricted to particular models: any model available
through the providers configured for the Zuplo project is accepted. An
unrestricted app has no default model, so every request must name one as
`providerName/model`. A request with no model, or a model without that prefix,
gets a `400`.

To limit an app to specific models, add the **Model Filtering** policy to the
app's [policy chain](./policy-chains.mdx)—models are controlled by that policy,
not by the app's settings. Open the app's **Policies** tab, add Model Filtering,
and configure each capability (completions, embeddings) in one of two modes:

- An **allow list** exposes a curated set of models. Only listed models are
  accepted, and the first entry is the default when a request doesn't specify a
  model.
- A **block list** permits every available model except the ones named. Each
  request must name its model, because a block list supplies no default.

The two modes are mutually exclusive per capability: a capability takes an allow
list or a block list, never both.

| Request                                                                                        | Response                      |
| ---------------------------------------------------------------------------------------------- | ----------------------------- |
| A model the rules don't allow                                                                  | `403`, listing what's allowed |
| No `model` named, with no allow list to supply a default                                       | `400`                         |
| A model with no `providerName/` prefix                                                         | `400`                         |
| A capability the policy doesn't configure at all                                               | `403`                         |
| A provider name that isn't in the Zuplo project's [provider catalog](./managing-providers.mdx) | `400`                         |

When model selection needs logic instead of a list, a custom policy can take
over—see [Dynamic model routing](./cookbooks/dynamic-model-routing.mdx).

## Setting budgets

App budgets live on the **Budgets and Costs** policy in the app's chain. Open
the app's **Policies** tab and add budget rules capping spending, tokens, or
requests over an hourly, daily, weekly, or monthly period—either for the app as
a whole or per metadata value, so each caller gets its own budget. Pool and
gateway limits apply to every app automatically, even when the app's chain
doesn't include Budgets and Costs. See [Usage Limits](./usage-limits.mdx).

## Editing an App

To edit an app, open the
[Apps](https://portal.zuplo.com/+/account/project/ai/apps) tab of your AI
Gateway project in the Zuplo Portal. Select the app you want to edit. The app's
behavior—models, app-specific budgets, caching, guardrails—is edited on the
**Policies** tab; the app's name lives on the **Settings** tab. Make your
changes and click the **Save** button. Policy chain changes apply within about a
minute.

## Deleting an App

To delete an app, open the
[Apps](https://portal.zuplo.com/+/account/project/ai/apps) tab of your AI
Gateway project in the Zuplo Portal. Select the app you want to delete, open its
**Settings** tab, and click the **Delete App** button. You will be prompted to
confirm the deletion.