Skip to content
AI

Custom Providers

Pro Exclusive

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 providerQuick AI in Raycast answering with Claude Fable 5.1, with the model picker open showing models from a custom Vercel AI Gateway provider

Custom provider requests are routed directly from your device to the provider's servers, bypassing Raycast entirely. Your API keys stay in the file on your device, and you pay the provider's standard rates for messages.

Get Started

  1. Open Settings → AI 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.
  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 countsThe Custom Providers section in Raycast's AI settings, listing Vercel AI Gateway, OpenClaw, LM Studio, and LiteLLM with their model counts

The file lives at ~/.config/raycast/ai/providers.yaml inside your user folder on both macOS and Windows.

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:

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

FieldRequiredDescription
idYesUnique identifier for the provider entry
nameYesProvider name shown in Raycast
base_urlYesOpenAI API compatible endpoint, without the /chat/completions suffix
api_keysNoMap of key aliases to API keys, omit for providers that don't require authentication
additional_parametersNoExtra fields added to every /chat/completions request
include_user_emailNoSet to true to send your signed-in Raycast email as an X-User-Email header, useful for per-user attribution on a shared gateway
modelsYesList of models to register, providers without any valid models are skipped

Model Fields

FieldRequiredDescription
idYesModel identifier, must match the id the provider's API expects
nameYesModel name shown in Raycast
providerNoSelects which alias in api_keys to use, defaults to the first key
descriptionNoShort description shown in Raycast
contextNoContext window size in tokens, refer to the provider's documentation
abilitiesNoCapability 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.

AbilityEnables
temperatureSending a temperature value with requests
visionImage attachments in prompts
system_messageSending a system message
toolsTool use, required for AI Extensions
reasoning_effortReasoning effort control for reasoning models

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

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.

Examples

Cross-vendor gateways such as Vercel AI Gateway or Cloudflare 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:

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 Keys 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

Chat with Raycast AISend Feedback