> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vybe.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Models and Models Gateway

> Tune how Auto picks AI models for your organization, and pay for AI usage with your own gateway key

Owners and Admins control two things about AI models for the whole organization: how **Auto** picks a model for each conversation, and who pays for AI usage. By default Vybe picks the models and bills usage in Vybe credits. You can change Auto's choices, and you can connect your own Vercel AI Gateway or OpenRouter key so model usage is billed there instead.

## How model choice works

Each AI coworker has its own model. New coworkers use **Auto** ("Automatic model selection"), which picks a model for you. You can also pin a coworker to a specific model from the model pill in its chat. Changing it there changes the model for that coworker for everyone, not just for you. See [Chatting with a coworker](https://docs.vybe.build/coworkers/chatting.md) and the [model list](https://docs.vybe.build/reference/ai-models.md).

The settings on this page change what Auto does across your organization. A coworker pinned to a specific model keeps that model.

## Auto model

When a coworker runs on Auto, "Vybe classifies each new conversation and picks a model for it." It works in two steps:

1. **Buckets.** Auto sorts the conversation into a kind of work, such as "Reading and reporting", "Writing original content" or "Debugging or investigating".
2. **Tiers.** Each bucket points to a tier: **Cheap**, **Balanced** or **Smart**. Each tier runs on a model.

Simple lookups go to a cheaper model, and harder work goes to a more capable one. Vybe sets the default buckets, tiers and models, and may update them over time.

### Customize Auto for your organization

Owners and Admins can change Auto's choices in **Settings → AI → Auto model**. Changes apply to your organization only. "Anything you leave alone keeps tracking the platform default, including changes we make later."

The page has two sections, each with its own **Tiers** and **Buckets**:

* **Conversations**: "Chat, Slack, scheduled tasks and triggers. The channel does not change the pick."
* **Coding agent**: "The app builder and delegated coding work, which is also asked how hard the task is." This section also sorts work into **Easy task** and **Hard task**.

What you can change:

| Change | How |
| - | - |
| Use a different model for a tier | Pick a model next to **Cheap**, **Balanced** or **Smart** under **Tiers** |
| Send a bucket to a different tier | Pick a tier in the bucket's model-or-tier picker. It then follows that tier's model |
| Pin a bucket to one model | Pick a model in the same picker. It stays on that model whatever the tier does |
| Reword a bucket | Edit its description. "The description is what the classifier reads" |
| Switch a bucket off | Stop offering it to the classifier. You can bring it back later |
| Add your own bucket | Click **Add a bucket**, give it a name and a description of when to use it, then click **Add bucket** |

Click **Save** to apply your changes, or **Discard changes** to drop them. **Revert to platform defaults** removes every change on the page.

> [!TIP]
>
> Add a bucket for work that matters to your team. For example, a bucket named "Contract review" with the description "Reviewing or drafting contracts, terms or legal language", pinned to your strongest model.

### Auto Model Instructions

For rules that are easier to write in words, use **Auto Model Instructions** in **Settings → Organization → General** (Owners and Admins, up to 4,000 characters). "Add rules here to extend or override that choice for your organization, in plain language." For example:

> Anything about invoices or contracts must run on the strongest model.
>
> Messages from the #support channel are routine: use a cheap model unless the user is upset.

## Models Gateway

"Vybe bills AI usage by default. Use your Vercel AI Gateway or OpenRouter key to pay directly." With a Models Gateway, AI model usage for your whole organization is billed to your gateway account instead of using Vybe credits.

Everyone except Guests can see the gateway's status in **Settings → AI → Models Gateway**. Only Owners and Admins can set it up or change it. Others see "Only organization owners and admins can change these settings."

### What changes when a gateway is active

* "Your gateway pays for AI model usage. Vybe charges zero AI model credits."
* Vybe credits still pay for people and company search and enrichment.
* Usage stays visible in Vybe. **Settings → AI → Usage** can split usage by **Billing source**.
* Auto and its tiers use the models you choose during setup. "Agents pinned to a specific model keep that choice."
* "Gateway errors stop AI requests." If your gateway fails, requests fail too. They don't switch to Vybe credits.
* "Deep research requires Vybe billing", so it isn't available while a gateway is active.

### Set up a gateway

**1. Start setup**

Go to **Settings → AI → Models Gateway** and click **Set up a gateway**.

**2. Add key**

Choose a **Gateway**: **Vercel AI Gateway** or **OpenRouter**. Paste your **API key** (use **Get API key** if you need one), then click **Continue**. Vybe checks that the key works.

**3. Check models**

Click **Run recommended checks**. Vybe tests the models it needs on your gateway. Each test uses a small amount of gateway credit.

Review the tier models for **Agents**, **Coding** and **Internal tasks**. **Agents** and **Coding** each have **Cheap**, **Balanced** and **Smart** tiers. **Internal tasks** has one **Ultra fast** tier for quick background work, such as naming and routing. If a model isn't available on your gateway, pick a replacement. "Required models must pass before activation." Then click **Review setup**.

**4. Review & activate**

Check the gateway, the tier models and the check results. "Check what will change for everyone in your organization." Then click **Activate Models Gateway**.

> [!NOTE]
>
> If some models fail their checks, the review step lists them under **Some models could not be used**: "Agents using these models may fail." Pick a tested model for any coworker that uses one, or fix access to the model in your gateway account.

Vybe stores your gateway key encrypted. After setup it only shows a masked version.

### Manage or remove the gateway

When a gateway is active, the page shows its status (**Active** or **Needs attention**), the masked key, and who added it and when. From there you can:

* **Check models**: run the model checks again, for example after you enable new models in your gateway account.
* **Change gateway or key** (pencil icon): replace the key or switch gateways. "Your current gateway stays active until you activate these changes."
* **View usage**: open the usage dashboard.
* **Delete gateway**: "New AI requests will automatically use Vybe credits. The stored key will be deleted."

### Troubleshooting

> **Chat shows "Models Gateway needs attention"**
>
> Your gateway can't serve requests. Either the key no longer works, or a tier model isn't available on your gateway account. An Owner or Admin should open **Settings → AI → Models Gateway**, then update the key or run **Check models** and choose available replacements. Deleting the gateway switches new requests back to Vybe credits.

> **A coworker says the model is unavailable on your organization's gateway**
>
> The coworker uses a model your gateway account can't run. Choose an available model in the coworker's model settings, or enable the model in your gateway account and run **Check models** again.

> **Model checks show "No compatible models found"**
>
> Your gateway account doesn't give access to any models Vybe can use. Enable model access in your gateway account, then click **Refresh model list**, or use a different key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.