Custom Providers

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.

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 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 file lives at ~/.config/raycast/ai/providers.yaml inside your user folder on both macOS and Windows.

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:

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

Model Fields

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.

The providers.template.yaml file installed next to your config documents the same format with complete annotated examples.

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.

Image generation isn't available for custom provider models.

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.

tools:
  web_search: raycast            # shorthand
  read_page:                     # object form
    provider: tavily
    api_key: TAVILY_KEY
  chart: false                   # off, same as leaving it out

To use one service for both web tools, share the entry with a YAML anchor:

tools:
  web_search: &tavily
    provider: tavily
    api_key: TAVILY_KEY
  read_page: *tavily

Tool Providers

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:

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

{ "query": "raycast founders", "max_results": 10, "country": "US" }

{
"results": [
{ "url": "https://example.com", "title": "Example", "content": "A snippet of the page" }
]
}

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

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

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, AI Chat, and 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 unlocks its full catalog automatically. If you run local models with Ollama, Raycast supports this natively with Local Models and detects your models automatically for you.

FAQ

Troubleshooting