Add a custom AI provider

A custom provider connects Granular to an AI service you choose, using the service's web address, your own API key and the names of the models you want. Add it from the connection menu under the message box. It costs nothing extra on any Granular plan, and your provider bills you directly.

What a custom provider is

A custom provider is one of several ways to put an AI model behind a session. The others are signing in with an AI account, pasting a key from Anthropic, OpenAI or Google, or using the AI Add-on (Granular Hosted). See Connect an AI model for all of them.

A custom provider is for you if:

• you already pay for an AI service Granular doesn't have a built-in option for, such as OpenRouter, Z.ai, MiniMax, Groq or DeepSeek, or
• you run a model on your own computer, such as with Ollama or LM Studio, or
• you want one key to open many models from different companies.

Your requests go from your computer straight to your provider. Granular's servers are not in the path, and no Granular credits are spent.

Before you start

You need three things from your provider. They are usually on its "API" or "Developers" page.

• The base URL. The web address where the service accepts requests, for example https://openrouter.ai/api. (An endpoint or base URL is simply the address software sends its AI requests to.)
• An API key. A long password that lets software use your account. Create one on your provider's website.
• The model names, exactly as your provider writes them, for example anthropic/claude-sonnet-4.5.

You also need to know which format your provider speaks. A format is the "language" a service expects requests in. Your provider's documentation will usually say one of these:

• Anthropic-compatible: it accepts requests the way Claude's service does, at an address ending in /v1/messages. Choose this if your provider offers it. OpenRouter, Z.ai and MiniMax do.
• OpenAI-compatible: it accepts requests the way OpenAI's service does, at an address ending in /chat/completions. Most other providers and local tools work this way, including Ollama, LM Studio, Groq, Together, DeepSeek, Azure and Google's Gemini.

If both are offered, pick Anthropic-compatible. Granular speaks that format natively. With OpenAI-compatible, Granular translates each request on your computer, and a few features don't carry over (see Limits).

Add a custom provider

1. In the row of controls under the message box, click the button that shows your current connection's name, such as Claude or G.hosted. If nothing is connected yet, it reads Connect an agent.
2. Click Add your AI agent.
3. Click Add custom provider.

4. In Name, type what you want to see in the menu, for example OpenRouter.
5. In Format, choose Anthropic-compatible or OpenAI-compatible.
6. In Base URL, paste your provider's address.
   • For Anthropic-compatible, leave off any /v1 at the end. Granular adds /v1/messages itself and removes a trailing /v1 for you.
   • For OpenAI-compatible, keep the /v1 your provider shows. Granular adds /chat/completions after it.
7. In Model ids, type one model name, or several separated by commas. The first one is the default.
8. In API key, paste your key.
9. Click Add & test.

What you'll see

After you click Add & test, the form shows Testing your provider - running the smallest real turn…. Granular sends your provider one tiny message ("reply with ok") using your first model, so a wrong address, key or model name shows up now rather than in the middle of a task. This uses a very small amount of your provider credit.

• If it works, you see a green tick and Connected - your provider answered a test run. You're ready to go. Click Done.
• If it doesn't work, the form may show a red ! with the likely cause and your provider's own words after Provider said:. Click Edit details to fix the form, or Done to close it.
• If the test can't tell what went wrong, the form waits for about a minute and a half, then says The test run didn't finish in time. The provider was saved - use "Test" on its row to try again. That means the test did not succeed. Check the address, key and model name, or send a short message in the chat: if something is wrong, the chat names the cause.

See Troubleshooting for each message.

Either way, the provider is saved. It appears in the connection menu's Accounts list with a plug icon, its name, and its default model. If you stacked several models it also shows + and how many more, for example · anthropic/claude-sonnet-4.5 +2. A small ✓ after the name means a test or a real message has worked on it; point at it to see which. No mark means Granular hasn't confirmed it works yet.

Granular also switches the current session to the new provider.

Stack several models and choose one per message

One custom provider can hold up to 20 models that share the same address and key. This is useful with a service like OpenRouter, where one key opens models from many companies.

• Type the model names in Model ids separated by commas, for example anthropic/claude-sonnet-4.5, google/gemini-2.5-pro, deepseek/deepseek-chat-v3.1. Spaces between them also work.
• The first name is the default. It runs when you haven't picked one.
• While a session uses this provider, the model button under the message box lists every model in the stack. Pick one, and your next messages use it. If the address belongs to a provider Granular knows (such as OpenRouter or DeepSeek), the menu also offers that provider's current list. You can search it and pin favourites; see Pick and pin models.
• Granular remembers your pick for this provider in this project.

Example: OpenRouter

OpenRouter is a marketplace that sells access to models from many companies through one key. It offers both formats, and Granular has been tested with each.

Anthropic-compatible (recommended):

• Format: Anthropic-compatible
• Base URL: https://openrouter.ai/api
• Model ids: OpenRouter's names, which start with the company, for example anthropic/claude-sonnet-4.5, google/gemini-2.5-pro
• API key: your OpenRouter key

OpenAI-compatible:

• Format: OpenAI-compatible
• Base URL: https://openrouter.ai/api/v1 (note the /v1 stays)
• Model ids and key: the same as above

Check OpenRouter's model list for the current names. You pay OpenRouter at OpenRouter's prices.

Use an OpenAI-only service or a model on your own computer

You don't need any extra software. Choose OpenAI-compatible in Format, and Granular translates between its own format and your provider's on your computer.

For Ollama or LM Studio at their usual address you don't need this form: Granular finds them when you open the connection menu. See Local models (Ollama, LM Studio).

For another tool that runs a model on your own computer:

1. Start the model in that tool as its instructions describe.
2. Find the local address it gives you. It starts with http://localhost or http://127.0.0.1 followed by a port number, and usually ends in /v1.
3. Add a custom provider with Format set to OpenAI-compatible, that address as the Base URL, and the model's name as the Model id.
4. If the tool doesn't need a key, type any placeholder text in API key. The form needs something in that box.

Plain http:// addresses are allowed only for your own computer. Everything else must start with https://.

Change or undo it

Each provider in the Accounts list has a ⋯ button that appears when you point at its row. Click it to see:

• Test account: runs the same tiny test again on the first model. A ✓ appears after the name if it works.
• Edit provider: opens the form again, titled Edit custom provider, with your details filled in.
• Remove: deletes the provider.

Edit or rename a provider

1. Open the connection menu, point at the provider, click ⋯, then Edit provider.
2. Change what you need:
   • To rename it, change Name. There is no separate rename button.
   • To add or remove models, edit Model ids. To change the default, put that model first.
   • To change the key, paste the new one. Leave API key empty to keep the key you already saved.
3. Click Save & test. Granular runs the test again with your changes.

Every session that uses this provider picks up the change.

Remove a provider

Open the connection menu, point at the provider, click ⋯, then Remove. There is no confirmation, and the saved key is deleted with it. Any session that was using it moves to another of your connections. If a project used it as its default, Project settings shows a red note that the default account was removed, until you pick another under Default account for new sessions.

To use the provider again later, add it again with its key.

Where your key is kept

Your API key is stored encrypted on your computer, never in a plain text file, and is sent only to the provider's address you entered. It is kept in the same encrypted store as the Vault, but it does not appear as an entry in the Vault list, and Granular never shows it again after you save it. To change it, use Edit provider.

The Vault is for keys your own projects use, such as a payment service your website calls. Keys that run Granular's agent go in the connection menu.

Limits

• Two formats. Your provider must be Anthropic-compatible or OpenAI-compatible. Other formats don't work.
• Some features don't carry over on OpenAI-compatible. Granular's translation leaves out the model's separate "thinking" steps and prompt caching (a feature that makes repeated requests cheaper), and some providers don't report how much text was used, so usage and context figures may be missing or estimated.
• https only, except your own computer. Remote addresses must start with https://. Plain http:// works only for localhost, 127.0.0.1 or [::1].
• Google's own Gemini address works only on OpenAI-compatible. On Anthropic-compatible the form refuses it.
• Up to 20 models per provider. Add another custom provider with the same address and key if you need more.
• Model names must start with a letter or number, use only letters, numbers, dots, dashes, underscores, slashes and colons (as in qwen3:8b or deepseek/deepseek-r1:free), and be 100 characters or fewer.
• The name can be up to 60 characters.
• The test checks only the first model. The others share the same address and key, so they usually work too, but a typo in a later model name only shows up the first time you use that model.
• Only the models you listed run. A session on this provider can use only the model names saved in it.
• Pick models that can use tools. Granular's agent works by using tools, such as reading files and running commands. Choose models your provider lists as supporting "tool use" or "function calling".
• The context gauge may be a guess. For models Granular doesn't recognise, the figure for how much the model can hold at once starts as an estimate and corrects itself as you use it.
• No Claude account connectors or Claude in Chrome. Those come with a Claude sign-in, so chats on a custom provider don't get them, and they aren't listed in those chats. Every other connector works. See Connectors in chat.

Troubleshooting

Messages when you click Add & test or Save & test

If you see "Give this provider a short name."
Type something in Name, up to 60 characters.

If you see "Enter your provider's API endpoint (a URL)."
Base URL is empty. Paste the address from your provider's documentation.

If you see "That doesn't look like a valid URL. It should start with https://"
Check for a typo or a missing https:// at the start.

If you see "The endpoint must be an http(s) URL."
The address starts with something other than https:// or http://. Use the web address your provider documents.

If you see "Use https:// for a remote endpoint (your key would travel unencrypted over http)."
Change http:// to https://. Plain http:// is allowed only for a model on your own computer at localhost.

If you see "That's Google's native Gemini API - it doesn't speak the Anthropic format."
Change Format to OpenAI-compatible and use https://generativelanguage.googleapis.com/v1beta/openai as the Base URL. Or, simpler, add a Gemini API key instead: see Connect Gemini.

If you see "Enter at least one model id your provider expects."
Model ids is empty. Type at least one model name.

If you see a model name followed by "doesn't look like a model id"
That name has a character a model name can't contain, such as a quote mark or a colon. Copy the exact names from your provider's model list and separate them with commas.

If you see "That's 21 models - keep one provider to 20 or fewer." (or another number)
Remove models until there are 20 or fewer, or split them across two providers.

If you see "Paste the API key your provider gave you."
API key is empty. New providers need a key. (When editing, an empty box keeps the saved key.)

If you see "That API key looks too long."
You may have pasted extra text along with the key. Copy just the key again.

If you see "That custom provider no longer exists."
The provider was removed while you were editing it. Close the form and add it again.

If you see "Heads up: this URL has no /v1"
This is a warning, not an error, on OpenAI-compatible. Most such addresses end in /v1. Add it unless your provider says otherwise.

Messages from the test

If you see "The test run didn't finish in time."
This is the most common sign that the test did not succeed. Either your provider took longer than about 90 seconds to answer, or it returned an error Granular couldn't classify. The provider is saved.

1. Check the Base URL, Format, key and first model name with ⋯, then Edit provider.
2. Send a short message such as "hi" in a chat that uses this provider. If something is wrong, the chat shows a message naming the cause. Look it up in Messages in the chat while you work.
3. If the chat reply works, the provider is fine. The ✓ appears after that first real reply.

If you see "Couldn't reach that Base URL."
Granular couldn't connect to the address. Check it is typed exactly, that it starts with https://, and that your internet is working. For a local model, check the tool is running.

If you see "The endpoint rejected the API key."
Check you copied the whole key, that it is still active, and that it belongs to this provider. Click Edit details, paste it again, and click Save & test.

If you see "The endpoint returned not found"
Either a model name is not one this provider offers, or the address points to the wrong place. Check both. The most common slips:

• On Anthropic-compatible: the address points at a service that doesn't speak that format. (A trailing /v1 is removed for you.)
• On OpenAI-compatible: the /v1 at the end of the address is missing.

If you see "The test run failed. See the provider's own message below."
Granular couldn't tell the cause. Read the text after Provider said:, which comes straight from your provider, and check your provider's dashboard.

If a provider row shows a red !
Granular has recorded that this provider can't work as set up. Point at the ! to read the reason, fix it with Edit provider, and test again.

If no ✓ appears after Test account
The test didn't confirm the provider works. Follow the steps under "The test run didn't finish in time" above.

Messages in the chat while you work

If you see "Your custom provider rejected the API key."
The key stopped working, for example because it was deleted or expired. Open ⋯, then Edit provider, paste a new key, and click Save & test.

If you see "The custom provider … couldn't be read (its key or endpoint is missing)."
Granular couldn't read the saved key. Open Edit provider, paste the key again and save. If that doesn't help, remove the provider and add it again.

If you see "Starting the local translation proxy for this OpenAI-compatible provider - try that again in a moment."
Granular's translator was still starting. Send your message again.

If you see "You have run out of tokens with …"
Your provider says your account has no credit left. Top up on your provider's website, or click Open the model picker and switch this session to another connection.

If you see "… is asking us to slow down." or "… is rate-limiting this model right now"
Your provider is limiting how fast you can send. Wait about a minute and send again.

If you see "… is temporarily overloaded"
The problem is on your provider's side. Wait a moment and try again.

If you see "You have used up your … allowance." or "You have used up this session's allowance."
Your provider has capped this model or your plan for now. Click Pick another model, or wait until the time the message gives.

If you see "This request was too big for …"
The conversation plus your connected tools no longer fit in what this model can hold. Click Change model or connectors to turn off some connectors or pick a model with a bigger window, or start a fresh chat.

If you see "Granular could not reach …"
Your computer seems to be offline or a network is blocking the address. Check your connection and send again.

If you see "… could not finish this turn."
Something went wrong on your provider's side and Granular couldn't tell what. Sending again is usually worth a try. The card can also show your provider's own error text, which helps if you contact them.

If you see "… isn't available on this account - using …"
The model you picked earlier is no longer in this provider's list, for example because you edited it out. Granular has switched to the default. Pick another model from the model button, or add the model back with Edit provider.

Related