# Custom Providers > Available on: Mac, Windows > Tier: Pro Exclusive Connect any compatible provider to Raycast AI and bring your own models, from cloud gateways and team proxies to agents running on your machine. Custom Providers let you connect any compatible provider to Raycast and bring your own models. The models you define appear in the model picker alongside Raycast AI models, ready to use across AI features. This is the most flexible way to bring outside models into Raycast, covering aggregators, cross-vendor gateways, and self-hosted proxies alike. ![Quick AI in Raycast answering with Claude Fable 5.1, with the model picker open showing models from a custom Vercel AI Gateway provider](https://fz1sd71lwhbqy6sh.public.blob.vercel-storage.com/raycast/images/app/ai/mac-custom-providers-quickai.png) > [!NOTE] > Requests to your custom models are routed directly from your device to the provider's servers, without passing through Raycast. Your API keys stay in the file on your device, and you pay the provider's standard rates for messages. > [!NOTE] > Tools such as web search are opt-in through the [`tools` block](#tools) in your config. Only tools set to `raycast` run on Raycast's servers, which requires Raycast Pro. Image generation isn't available for custom provider models. ## Get Started 1. Open **Settings → AI → Models & Providers** and scroll down to the **Custom Providers** section. 2. Click **Reveal Providers Config**. Raycast opens the config folder and places a `providers.template.yaml` file inside it, documenting the file format. 3. Copy the template to a file named `providers.yaml` in the same folder, then edit it with your providers and models. The template's `tools` block enables all four [tools](#tools) through `raycast`, so remove the block if you don't want your models to use them. 4. Save the file. Raycast watches it for changes, so your providers and their model counts appear in the Custom Providers section right away, with no restart needed. ![The Custom Providers section in Raycast's AI settings, listing Vercel AI Gateway, OpenClaw, LM Studio, and LiteLLM with their model counts](https://fz1sd71lwhbqy6sh.public.blob.vercel-storage.com/raycast/images/app/ai/mac-custom-providers-settings.png) The file lives at `~/.config/raycast/ai/providers.yaml` inside your user folder on both macOS and Windows. > [!WARNING] > If Raycast can't read your file, an **Invalid providers.yaml** badge appears next to Providers Config in Settings. Hover over the badge to see exactly what went wrong. Your previously loaded models keep working while you fix the file. ## Configuration Format Each entry in the `providers` list needs an `id`, a `name`, an OpenAI API compatible `base_url`, and a list of `models`. Here's a trimmed example connecting a provider with one model: ```yaml providers: - id: my_provider name: My Provider base_url: https://api.example.com/v1 api_keys: my_provider: YOUR_API_KEY models: - id: my-model-id name: My Model provider: my_provider description: A short description shown in Raycast context: 200000 abilities: temperature: supported: true vision: supported: true system_message: supported: true tools: supported: true reasoning_effort: supported: false ``` ### Provider Fields | Field | Required | Description | | --- | --- | --- | | `id` | Yes | Unique identifier for the provider entry | | `name` | Yes | Provider name shown in Raycast | | `base_url` | Yes | OpenAI API compatible endpoint, without the `/chat/completions` suffix | | `api_keys` | No | Map of key aliases to API keys, omit for providers that don't require authentication | | `additional_parameters` | No | Extra fields added to every `/chat/completions` request | | `include_user_email` | No | Set to `true` to send your signed-in Raycast email as an `X-User-Email` header, useful for per-user attribution on a shared gateway | | `models` | Yes | List of models to register, providers without any valid models are skipped | ### Model Fields | Field | Required | Description | | --- | --- | --- | | `id` | Yes | Model identifier, must match the id the provider's API expects | | `name` | Yes | Model name shown in Raycast | | `provider` | No | Selects which alias in `api_keys` to use, defaults to the first key | | `description` | No | Short description shown in Raycast | | `context` | No | Context window size in tokens, refer to the provider's documentation | | `abilities` | No | Capability flags for the model, see below | ### Abilities Each ability is optional and takes a `supported: true` or `supported: false` value. When omitted, Raycast assumes system messages and temperature are supported, and tool use and vision are not. Declaring an ability the model doesn't actually support can make requests fail. | Ability | Enables | | --- | --- | | `temperature` | Sending a temperature value with requests | | `vision` | Image attachments in prompts | | `system_message` | Sending a system message | | `tools` | Tool use, required for AI Extensions and [tools](#tools) | | `reasoning_effort` | Reasoning effort control for reasoning models | The `providers.template.yaml` file installed next to your config documents the same format with complete annotated examples. > [!NOTE] > The OpenAI API is not a formal standard, so we can't guarantee that every provider works correctly with Raycast AI. Refer to your provider's API documentation for model identifiers and capabilities. ## Tools Custom provider models can use Raycast's tools, such as web search and reading web pages, when your `providers.yaml` has a top-level `tools` block. Tools are opt-in: without the block, custom provider models get no tools at all. A model only uses tools if it declares `abilities.tools.supported: true`, and the block applies to every model in the file, with no per-provider or per-model overrides. | Tool | What it does | Supported providers | | --- | --- | --- | | `web_search` | Searches the web, with source cards and citations | `raycast`, `custom`, `tavily`, `exa`, `firecrawl`, `brave`, `perplexity` | | `read_page` | Reads a web page you or the model provide | `raycast`, `custom`, `tavily`, `exa`, `firecrawl`, `jina` | | `search_images` | Finds images | `raycast` | | `chart` | Renders charts | `raycast` | Image generation isn't available for custom provider models. > [!NOTE] > The `tools` block doesn't affect OpenRouter models added through [Bring Your Own Key](https://manual.raycast.com/ai/bring-your-own-key), which keep using OpenRouter's `:online` web search. Installed [AI Extensions](https://manual.raycast.com/ai/ai-extensions) such as Exa Search or Perplexity also keep working with any tool-capable model, independent of the block. ### Entry Format Each tool takes either a provider name or an object with the provider and its settings. Leaving a tool out or setting it to `false` turns it off. ```yaml tools: web_search: raycast # shorthand read_page: # object form provider: tavily api_key: TAVILY_KEY chart: false # off, same as leaving it out ``` | Field | Applies to | Description | | --- | --- | --- | | `provider` | All | Required. The service that runs the tool | | `api_key` | Vendors, `custom` | Plain-text key. Required for `tavily`, `exa`, `firecrawl`, `brave`, and `perplexity`. Optional for `jina`, where anonymous use is rate limited, and for `custom` | | `base_url` | Vendors | Replaces the vendor's API address, for example to route through a proxy in front of the vendor | | `url` | `custom` | Required. Your gateway endpoint, called exactly as written | | `headers` | Vendors, `custom` | Extra request headers, with string values only. They're applied after the vendor's auth header, so they can replace it | | `include_user_email` | Vendors, `custom` | Set to `true` to send your signed-in Raycast email as an `X-User-Email` header. Off unless set to exactly `true` | | `max_results` | `web_search` | Maximum number of results returned to the model. Defaults to 10, between 1 and 20 | To use one service for both web tools, share the entry with a YAML anchor: ```yaml tools: web_search: &tavily provider: tavily api_key: TAVILY_KEY read_page: *tavily ``` ### Tool Providers | Provider | Where requests go | Authentication | Default address | | --- | --- | --- | --- | | `raycast` | Raycast's servers, requires Raycast Pro and no extra key | Your Raycast account | – | | `custom` | Your own gateway, see [Custom Gateway](#custom-gateway) | `Authorization: Bearer ` if set | `url` | | `tavily` | Tavily `/search` and `/extract` | `Authorization: Bearer` | `https://api.tavily.com` | | `exa` | Exa `/search` and `/contents` | `x-api-key` | `https://api.exa.ai` | | `firecrawl` | Firecrawl `/search` and `/scrape` | `Authorization: Bearer` | `https://api.firecrawl.dev/v2` | | `brave` | Brave `/web/search`, search only | `X-Subscription-Token` | `https://api.search.brave.com/res/v1` | | `perplexity` | Perplexity Search API `/search`, search only | `Authorization: Bearer` | `https://api.perplexity.ai` | | `jina` | Jina Reader, read page only | `Authorization: Bearer` if set | `https://r.jina.ai` | Every provider except `raycast` is called directly from your device, through the system proxy if one is configured, so these requests never touch Raycast's servers. When a provider fails, the tool fails, and Raycast never falls back to another provider. The model sees the provider's error message, for example `Tavily returned 401: Invalid API key`. Your keys never appear in error messages. ### Custom Gateway Set a tool's provider to `custom` to run it on your own gateway. The gateway contract is a subset of Tavily's search and extract APIs, so a gateway that simply forwards to Tavily works as is. Raycast sends `POST` requests with a JSON body to the `url` you configure: ```yaml tools: web_search: provider: custom url: https://ai.example.com/web/search api_key: GATEWAY_KEY headers: X-Team: platform include_user_email: true read_page: provider: custom url: https://ai.example.com/web/extract api_key: GATEWAY_KEY ``` web_search read_page Raycast sends one request for each way the model phrases the search, up to 5, and merges the results. `country` is only included when the model asks for one, as an ISO 3166-1 alpha-2 code. Request: ```json { "query": "raycast founders", "max_results": 10, "country": "US" } ``` Response: ```json { "results": [ { "url": "https://example.com", "title": "Example", "content": "A snippet of the page" } ] } ``` Raycast sends the pages to read and expects their content back as Markdown. `title` and `failed_results` are optional, and the `error` of each failed result is shown to the model. Request: ```json { "urls": ["https://example.com/page"], "format": "markdown" } ``` Response: ```json { "results": [ { "url": "https://example.com/page", "raw_content": "# Markdown content", "title": "Example" } ], "failed_results": [ { "url": "https://example.com/other", "error": "Reason shown to the model" } ] } ``` Any response status other than 2xx counts as a failure. The `error`, `error.message`, `message`, or `detail` field of the response body is shown to the model. ### Limits - **Search requests** time out after 30 seconds, and each snippet is capped at 2,000 characters. - **Page reads** time out after 60 seconds, and page content is capped at 200 KB, marked with `[Content truncated]` when cut. - **`read_page`** only accepts `http` and `https` URLs. ### Invalid Configuration An invalid entry turns off only that tool, while your models and all other tools keep working. Common causes are a missing `api_key`, a provider that doesn't support the tool, a missing or non-http `url` for `custom`, and an unknown tool name. ## Examples Vercel AI Gateway LiteLLM Proxy AWS Bedrock LM Studio OpenClaw Hermes Agent Cross-vendor gateways such as [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) or [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/) put models from every major lab behind a single endpoint and a single key, with usage tracking and spend controls in one dashboard: ```yaml providers: - id: vercel_ai_gateway name: Vercel AI Gateway base_url: https://ai-gateway.vercel.sh/v1 api_keys: vercel: VERCEL_AI_GATEWAY_KEY models: - id: anthropic/claude-fable-5.1 name: "Claude Fable 5.1" context: 1000000 abilities: temperature: supported: true vision: supported: true system_message: supported: true tools: supported: true reasoning_effort: supported: true ``` Team proxies such as [LiteLLM](https://docs.litellm.ai/) let one gateway hold the vendor keys while everyone on the team points Raycast at it. Turn on the optional email header so the proxy can attribute usage to each person: ```yaml providers: - id: litellm name: LiteLLM base_url: http://localhost:4000 # Sends your signed-in Raycast email as an `X-User-Email` header, # e.g. for per-user attribution or quotas on a shared gateway include_user_email: true models: - id: anthropic/claude-sonnet-5 name: "Claude Sonnet 5" context: 1000000 abilities: temperature: supported: true vision: supported: true system_message: supported: true tools: supported: true ``` Cloud platforms like [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-chat-completions.html) let you use models under your existing cloud account and billing. Bedrock exposes an OpenAI compatible endpoint per region, authenticated with a Bedrock API key: ```yaml providers: - id: bedrock name: AWS Bedrock base_url: https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1 api_keys: bedrock: YOUR_BEDROCK_API_KEY models: - id: moonshotai.kimi-k2-thinking # use the Chat Completions model id from the Bedrock model catalog name: "Kimi K2 Thinking" context: 256000 abilities: temperature: supported: true system_message: supported: true tools: supported: true ``` Local runners such as [LM Studio](https://lmstudio.ai/) serve open models straight from your own machine, with no API key and no data leaving your computer. Enable the server in LM Studio's Developer tab, then list the models you've downloaded: ```yaml providers: - id: lmstudio name: LM Studio base_url: http://localhost:1234/v1 # No `api_keys` - the local server doesn't require authentication models: - id: qwen/qwen3-14b # use the model id shown in LM Studio's server page name: "Qwen 3 14B" context: 32000 abilities: temperature: supported: true system_message: supported: true tools: supported: true ``` Local agents work too. [OpenClaw](https://docs.openclaw.ai/gateway/openai-http-api)'s gateway exposes an OpenAI compatible API, so you can chat with an agent that has its own tools and memory straight from Raycast: ```yaml providers: - id: openclaw name: OpenClaw base_url: http://127.0.0.1:18789/v1 api_keys: # Your gateway token from `gateway.auth.token` or OPENCLAW_GATEWAY_TOKEN openclaw: YOUR_GATEWAY_TOKEN models: - id: openclaw/default # stable alias for your default agent name: "OpenClaw" description: Your local OpenClaw agent abilities: temperature: supported: true system_message: supported: true ``` You can also use [Hermes Agent](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server) inside Raycast AI, complete with its own tools, memory, and skills. Enable its API server with `API_SERVER_ENABLED=true` and an `API_SERVER_KEY` in `~/.hermes/.env`, start it with `hermes gateway`, then point Raycast at it: ```yaml providers: - id: hermes name: Hermes Agent base_url: http://127.0.0.1:8642/v1 api_keys: # The API_SERVER_KEY value from ~/.hermes/.env hermes: YOUR_API_SERVER_KEY models: - id: hermes-agent # the default profile, or use a profile name name: "Hermes Agent" description: Your local Hermes agent abilities: temperature: supported: true vision: supported: true system_message: supported: true ``` ## Using Custom Models Custom provider models show up in the model picker grouped under the provider's name you set in the file. Pick them anywhere you'd pick a Raycast AI model, including [Quick AI](https://manual.raycast.com/ai/quick-ai), [AI Chat](https://manual.raycast.com/ai/ai-chat), and [AI Commands](https://manual.raycast.com/ai/ai-commands). Since Raycast has no benchmark data for custom models, they don't show speed or intelligence scores in the model settings. If you only want models from OpenRouter, adding an OpenRouter API key via [Bring Your Own Key](https://manual.raycast.com/ai/bring-your-own-key) unlocks its full catalog automatically. If you run local models with Ollama, Raycast supports this natively with [Local Models](https://manual.raycast.com/ai/local-models) and detects your models automatically for you. ## FAQ ### Should I use Custom Providers or Bring Your Own Key? They solve different problems. [Bring Your Own Key](https://manual.raycast.com/ai/bring-your-own-key) is for when you want to keep using the models Raycast AI already offers, but pay Anthropic, Google, OpenAI, or OpenRouter directly with your own API key. Setup is a single key, and Raycast handles the rest. Custom Providers are for going beyond what Raycast AI supports natively. Use them to reach models from providers Raycast doesn't offer, or to route requests through a gateway, a team proxy, a local agent, or any other OpenAI API compatible endpoint. You describe the models yourself in a config file, in exchange for full control over where requests go. ### Can I manage custom providers for everyone in an organization? Yes, Enterprise organizations can upload a [Custom Provider Configuration](https://manual.raycast.com/enterprise/custom-provider) that applies to every member. When one is configured, it replaces your local `providers.yaml` entirely, including its `tools` block, and the Custom Providers section in settings shows that your organization manages the configuration. ### Are my API keys sent to Raycast? No. Your keys stay in the `providers.yaml` file on your device and aren't sent to Raycast. Requests to your custom models, and to any tool providers you configure with your own keys, go directly from your device to those providers. Only tools set to `raycast` in the [`tools` block](#tools) run on Raycast's servers. ### Do custom models use Raycast AI credits? Not for requests to your custom models. They go directly to your provider rather than through Raycast's servers, so they don't consume your [Raycast AI credits](https://manual.raycast.com/ai/ai-credits), and your only limits are the ones your provider sets for your key. Tools set to `raycast` in the [`tools` block](#tools) are the only part that runs on Raycast's servers, and they require Raycast Pro, with no extra key. ### Does my providers.yaml sync between devices? No. The file lives on disk outside of Cloud Sync, so each machine needs its own copy. Keep the file somewhere you can copy it from, or manage it with your own dotfiles setup. ## Troubleshooting ### I deleted or broke the template file Click **Reveal Providers Config** in **Settings → AI → Models & Providers** again. Raycast rewrites `providers.template.yaml` on every reveal, so it always documents the current schema. ### My custom model returns errors or behaves oddly First, test the same `base_url` and model id outside Raycast, for example with `curl`, to rule out a provider or key problem. If that works, the cause is almost always the `abilities` block. Double-check the model `id` matches the provider's identifier exactly, and review each ability against the provider's documentation. Declaring an unsupported ability, such as `tools` on a model without tool support, is the most common cause of failed requests. ### My models don't appear in the model picker after saving Work through these in order: 1. Open **Settings → AI → Models & Providers** and check for an **Invalid providers.yaml** badge next to Providers Config. Hover over it to see the parse error. 2. Make sure the file is named exactly `providers.yaml`, not `providers.template.yaml`, and sits in the `ai` folder that **Reveal Providers Config** opens. 3. Make sure each provider has at least one model with both an `id` and a `name`. Providers without valid models are skipped silently. 4. Check that the Custom Providers section doesn't say **Managed by your organization**. An organization configuration replaces your local file. 5. Confirm your Raycast Pro subscription is active, since custom models are Pro-only. ### A tool doesn't work with my custom model Work through these in order: 1. Make sure the model declares `abilities.tools.supported: true` and that your `providers.yaml` has a top-level `tools` block listing the tool. Without the block, custom provider models get no tools. 2. Check your Raycast logs for `Local providers.yaml has invalid tools entries`. An invalid entry, such as a missing `api_key` or a provider that doesn't support the tool, turns off only that tool, and the log line explains why. 3. If the tool runs but fails, the model sees the provider's error message, for example `Tavily returned 401: Invalid API key`. Check your key and quota with that provider. Raycast never falls back to another provider. 4. For tools set to `raycast`, confirm your Raycast Pro subscription is active. 5. Check that the Custom Providers section doesn't say **Managed by your organization**. An organization configuration replaces your local file, including its `tools` block. ### Still having issues? If none of the above resolves it, gather the following and send it to us via the [Send Feedback](raycast://extensions/raycast/raycast/send-feedback) command so we can investigate (see [Contact Support](https://manual.raycast.com/contact-support) for more ways to get in touch): 1. **Your OS version** and **Raycast version** (found in **Settings → About**). 2. **Your `providers.yaml` contents**, with every value under `api_keys` and every `api_key` under `tools` replaced by `REDACTED`. Never share your real API keys. 3. The **error text** from the **Invalid providers.yaml** badge tooltip, if one is shown. 4. The **model** you picked and the **AI feature** you used when the request failed. 5. Whether a **direct request to the provider works** outside Raycast, for example with `curl` against the same `base_url` and model. 6. **Your Raycast logs**: use the built-in **Copy Raycast Logs** command to copy your latest log files to the clipboard, or **Reveal Raycast Logs** to open your log folder. --- ## Need Help? Contact Raycast Support if you have any questions or would like help with Custom Providers. Use the **Send Feedback** command directly in Raycast to report bugs and billing issues, log feature requests, or any other queries you would like to speak to us about. You can view all Raycast Support contact options at https://manual.raycast.com/contact-support