# Model provider

**Model provider** is where you connect your organization's own model key: an Anthropic API key,
an OpenAI API key, or your own LiteLLM proxy. Productmind's agents and coding sessions then run on
your account. Your provider bills those tokens directly, and they use no Productmind AI credits.

<Availability rollout plan="Depends on your plan. If yours doesn't include it, the Model provider tab shows a lock and names the plan that does." permission="Agents access on the Roles tab, under Administrative access, to see the tab. Connecting, changing, verifying or removing the key: the Owner or Admin role." />

## Key concepts

**Model key.** Your organization's own credential for a model provider. An organization has one
key, whichever workspace you open the tab from, and it applies to every workspace.

**Provider.** Where the key comes from:

| Provider | Agents use | Coding sessions run with |
| --- | --- | --- |
| **Anthropic API key** | Claude models, through the Anthropic API | Claude Code |
| **OpenAI API key** | OpenAI models, through the OpenAI API | Codex |
| **LiteLLM proxy** | the models your proxy serves, which you map to model classes | Claude Code, through the proxy's Anthropic-compatible endpoint |

**Model class.** Productmind asks for a class of model, never a specific model: **Quick**,
**Standard**, **Top** or **Ultra**. With an Anthropic or OpenAI key, Productmind picks the model
for each class. With a LiteLLM proxy, you pick which of the proxy's models serves each class, and
its **family**, which tells agents which request features the model supports.

**Where the key is used.** Three switches decide it:

- **Use for agents**: chat, document generation, prompts and the other agent work.
- **Use for coding sessions**: coding sessions in the Productmind cloud (plan, build, scan and
  live preview).
- **Also on developers' local agents**: sessions that developers run on their own machines with
  the Productmind agent. Off by default: they keep using their own login.

**Status.** What the tab shows about the key:

| Status | Means |
| --- | --- |
| **Pending verification** | The key hasn't passed its check yet, so nothing uses it. |
| **Active** | The key passed its check and is in use. |
| **Invalid** | The provider rejected the key. Work that needs it is refused until you replace it or it passes a new check. |
| **Suspended** | Your plan no longer includes bring your own model key. Work set to use the key is refused. |

**Runner.** Every coding session in the Productmind cloud runs on a runner of its own, which serves
no other session and no other organization. Your key is never used on a runner shared with anyone
else.

## The Model provider tab at a glance

In the sidebar, choose **Agents**, then **Model provider**.

The tab shows, from top to bottom:

- **Provider**: the three provider cards. Once a key is connected, the provider is fixed until
  you remove the key.
- **The key**: for a stored key, only its last four characters, with **Replace key**. For a
  LiteLLM proxy, the **Proxy URL**, the **Proxy key** and the **API format**, then the mapping of
  the four model classes.
- **Where this key is used**: the three switches.
- **The status card**, once a key is connected: its status, **Key** (the last four characters),
  **Last verified**, **Last used**, the last failed check if there is one, **Verify now** and
  **Remove key**.
- **Knowledge base indexing stays on Productmind**: a reminder that indexing and embeddings always
  run on Productmind's own models.

If you don't have the Owner or Admin role, the tab shows the key's configuration without the
forms.

## Connecting a key

### To connect an Anthropic or OpenAI key

1. In the sidebar, choose **Agents**, then **Model provider**.
2. Choose **Anthropic API key** or **OpenAI API key**.
3. In **API key**, paste the key.
4. Under **Where this key is used**, turn on the switches you want.
5. Choose **Save and verify**.

Productmind checks the key with a one-token call to each model class it uses. When the check
passes, the key's status is **Active** and new work runs on it. When it fails, the tab shows which
check failed and why, and nothing uses the key.

### To connect a LiteLLM proxy

1. In the sidebar, choose **Agents**, then **Model provider**.
2. Choose **LiteLLM proxy**.
3. Under **1. Connect the proxy**, enter the **Proxy URL** and the **Proxy key**, and choose an
   **API format**: **Anthropic (Messages API)** or **OpenAI (Chat Completions API)**.
4. Choose **Connect**. The tab shows how many models the proxy lists.
5. Under **2. Map the model classes**, pick a model for **Quick**, **Standard**, **Top** and
   **Ultra**. Productmind suggests each model's family; change it if it is wrong.
6. Under **Where this key is used**, turn on the switches you want.
7. Choose **Activate**.

Productmind checks each mapped model with a one-token call. When the check passes, the key's
status is **Active**.

:::note
The proxy URL must use HTTPS on a public address. Productmind calls it from its own servers, never
from your browser, so a proxy reachable only on your private network can't be used.
:::

### To choose where the key is used

1. In the sidebar, choose **Agents**, then **Model provider**.
2. Under **Where this key is used**, turn **Use for agents**, **Use for coding sessions** or
   **Also on developers' local agents** on or off.
3. Choose **Save changes**.

New work follows the new switches. A coding session already running on the key when you turn
**Use for coding sessions** off may stop at its next step; run it again to continue on Productmind AI
credits.

## Managing the key

### To replace the key

1. In the sidebar, choose **Agents**, then **Model provider**.
2. Choose **Replace key**, and paste the new key.
3. Choose **Save and verify**. For a LiteLLM proxy, connect again, then choose **Save changes**.

The new key is checked before it goes live. If the check fails, the current key stays in use and
the tab shows why the new one failed.

### To verify the key

1. In the sidebar, choose **Agents**, then **Model provider**.
2. On the status card, choose **Verify now**.

Productmind checks the key again with a one-token call to each model class. A key the provider
now rejects becomes **Invalid**.

### To remove the key

1. In the sidebar, choose **Agents**, then **Model provider**.
2. On the status card, choose **Remove key**.
3. Choose **Remove key** again to confirm.

:::caution
The key is deleted from Productmind and can't be recovered. New agent work and coding sessions use
Productmind AI credits. Runs already in progress may fail.
:::

## How the model provider behaves

**Your provider bills the tokens.** Work that runs on your key uses no Productmind AI credits and
counts toward no allowance. It appears on the **Usage** tab of **Billing & Payments** as
**Billed by your provider**, in tokens. Sandbox hours and the per-session fee for
sessions on developers' machines are billed as usual.

**Knowledge base indexing stays on Productmind.** Embeddings and knowledge base indexing always run
on Productmind's own models and use AI credits, whichever key is connected.

**Your key is never replaced silently.** If your key stops working, is suspended, or its settings
can't be read, work set to use it is refused with a message that points here. It doesn't move
onto Productmind AI credits on its own. When the provider rejects the key during a run,
Productmind checks it again, and if it still fails, marks it **Invalid** and tells your Owners and
Admins, in the app and by email.

**Coding sessions start on a runner of their own.** When a session has no runner yet, the
session says **Waiting for a runner. Your run starts as soon as one is free.** while it waits its
turn, then **Starting a runner. This can take a few minutes.** A live preview of
the session runs on the same runner. This is the same for every organization, with or without your
own key.

**If no runner is free in time, the run stops with Retry.** A run that waits more than 15 minutes
stops with **No runner became available for this session in time. Retry in a few minutes.**, and
one whose runner can't be started stops with **A runner could not be started for this session.
Retry in a few minutes.** Nothing moves onto Productmind AI credits: the run stays on your key, and
**Retry** runs it again. A scan waits longer for its runners, and a scan step that gets none says
so on the scan, which you can then start again.

**If the runner stops during a run, Productmind starts a new one, once.** The run moves there,
still on your key, and the session notes what happened to it:

- a plan continues: **The runner for this session stopped, so the run continues on a new one.**
- a build moves to the new runner, and the changes it had not pushed yet are made again: **The
  runner for this session stopped, so the run moved to a new one. Changes that had not been pushed
  yet are made again.**
- a change you asked for in the conversation, or a fix for review comments, continues, and the note
  adds that changes it had not pushed yet did not carry over.

A live preview that was running there has to be restarted. If the new runner stops too, the run
stops with **The runner for this session stopped again, so the run was stopped. Retry to run it
again.**

**With an OpenAI key, sessions run with Codex.** A session keeps the coding agent it started with.
If a later run of a Codex session runs on Productmind AI credits, for example after you remove the
key, it moves to Claude Code, which picks up from the conversation so far, and the session says so.
If you connect a key for the other agent, the session's next run moves to that agent the same way.

**Developers' local agents.** With **Also on developers' local agents** on, sessions a developer
runs on their own machine use your key instead of the developer's own login. With an OpenAI key,
the developer's Productmind agent needs Codex installed; otherwise the session is refused rather
than run on the developer's own login. With the switch off, local sessions run on the developer's
own login, as before.

**If your plan changes.** When your organization moves to a plan without bring your own model key,
the key is kept but **Suspended**: work set to use it is refused, not run on AI credits, and your
Owners and Admins are told. Change the plan to use the key again, or remove it to go back to
Productmind AI credits. See
[Features that depend on your plan](/user-guide/reference/plans-and-limits#features-that-depend-on-your-plan).

## Permissions

| To | You need |
| --- | --- |
| See the Model provider tab | **Agents** access (under **Administrative access** on the **Roles** tab) |
| Connect, replace, verify or remove the key, and change where it is used | The **Owner** or **Admin** role |

See [Roles and permissions](/user-guide/reference/roles-and-permissions).

## Limits

- One model key per organization.
- Saving, verifying and connecting are limited to 10 per minute per organization, because each
  one makes calls on your account.

## Troubleshooting

### The Model provider tab is missing

The feature isn't enabled for your organization yet, or you don't have **Agents** access. Ask
Productmind support to turn it on.

### "Model keys are not available in this environment"

This Productmind environment has no secure store for model keys, so a key can't be saved or
changed there.

### The check fails with "The proxy URL was refused"

The proxy URL doesn't use HTTPS, or its name resolves to a private address. Use a proxy reachable
over HTTPS on a public address.

### The check fails with "This key may not use this model"

The key works, but your provider account doesn't allow one of the models Productmind asked for.
Allow the model in your provider account or, for a LiteLLM proxy, map that class to a model the
key may use.

### A run stops with "No runner became available for this session in time"

The Productmind cloud had no runner free for the session within 15 minutes. Nothing ran, and
nothing moved onto Productmind AI credits. Choose **Retry** in a few minutes.

### A session is paused because your key reached its usage limit

Your provider stopped accepting requests on your organization's key because the account reached a
usage limit, such as a spend limit set in the provider's console. The session shows **Paused: model
capacity is used up**, with the time the provider says the limit resets, in your local time. Nothing
moves onto Productmind AI credits, and every session that runs on the key stops the same way until
then. Raise the limit in your provider account, or wait until the time shown. Then choose
**Resume**, or, if the run was a change you asked for in the conversation, send your message again.

### Work is refused with "Your organization's model provider key stopped working"

The provider rejected the key, and its status is **Invalid**. Replace the key, or choose **Verify
now** once it works again, or remove it to go back to Productmind AI credits.

### Work is refused with "Your plan no longer includes bring your own key"

The key is **Suspended**. Change the plan to one that includes bring your own model key, or remove
the key to go back to Productmind AI credits.

### A session on a developer's machine says "Your Productmind agent is too old"

The developer's Productmind agent can't use your organization's key yet. Run `pm update` on that
machine, then try again. See [Productmind CLI](/user-guide/tools/productmind-cli).

## Related topics

- [Agents](/user-guide/engineering/agents/overview)
- [Templates](/user-guide/engineering/agents/templates)
- [Usage](/user-guide/settings/billing-and-payments/usage)
- [Working in a session](/user-guide/sessions/working-in-a-session)
- [Plans and limits](/user-guide/reference/plans-and-limits)
