We believe the use of AI models in Surf should be open.
We've built a UI to switch between models on every query. We have architected Surf so that you can bring your own key for popular models or add your own custom model (either local or in the cloud).
Once added, your model will show up in the UI.
Surf's interface allows you to easily switch between models on the fly and use the one that best fits your needs. Just select it in the switcher.
You can enter your own API key by going to Preferences → AI and then selecting one of the built-in providers under “Configure your AI Models”.
Read OpenAI’s help page or visit Anthropic’s Claud Console for your API keys.
If you have not yet setup your own AI model, follow the instructions for some common providers below. Once you have your model running, you can add it to Surf by following these steps:
- Open the Surf settings through the app menu or using the shortcut
⌘/ctrl + , - Navigate to the “AI“ tab.
- Click on the "Add Model" button under the "Configure your AI Models" section.
- Give your model a name and most importantly, provide the URL where your model is hosted and the ID of the model itself.
The model URL should be the OpenAI compatible chat completions API endpoint where your model is hosted. The model ID is the unique identifier of your model. If your model requires an API key, you can provide it in the settings as well.
See below on what each configuration option means, you can usually find the required information in the documentation of your chosen provider.
Once you have added your model, you can start using it in Surf. Select it from the dropdown at the top of the settings page or from the Chat or Smart Notes editor.
Here is a list of the configuration options you can set when adding a new model to Surf:
| Option | Value |
|---|---|
| Provider URL | Full URL of the model provider's OpenAI compatible API endpoint, most likely follows this format https://<hostname>/v1/chat/completions |
| Model ID | The unique identifier or name of the model provided by the model provider |
| API Key | If the model provider requires an API key, provide it here |
| Context Size | The maximum number of tokens for the context window, can usually be found in your provider's documentation |
| Supports Vision | Whether the model supports vision tasks, check the provider's documentation |
| Supports JSON | Whether the model supports JSON output format, smaller or local models usually don't |
To use AI models running locally on your machine we recommend using Ollama. To get started follow their quick start guide to set it up locally and then use the following configuration options:
| Option | Value |
|---|---|
| Provider URL | http://localhost:11434/v1/chat/completions |
| Model ID | The model name provided by Ollama, check their model page for all available models |
| API Key | Can be left blank |
| Context Size | run ollama show <model name> to see the context window size of your Ollama model |
| Supports Vision | Whether the model supports vision tasks, check the model page for more info |
| Supports JSON | for local models it's best to disable this |
To use models hosted by OpenRouter first create an account, then generate an API key from their settings page. Use the following configuration options to connect it to Surf:
| Option | Value |
|---|---|
| Provider URL | https://openrouter.ai/api/v1/chat/completions |
| Model ID | The model ID provided by OpenRouter, check their models page for all available models |
| API Key | Your OpenRouter API key |
| Context Size | The maximum number of tokens for the context window |
| Supports Vision | Whether the model supports vision tasks, check the model page for more info |
| Supports JSON | Whether the model supports a JSON output forma, smaller models usually don't |
To use text generation models from Hugging Face you can use their routing service with one of their supported Inference Providers like Together AI.
As an example here’s how to use a Hugging Face model running on Together AI via Hugging Face:
- Sign up to Hugging Face if you haven’t
- Generate a Access Token in the Hugging Face settings
- Select a model from Hugging Face’s model page that supports Together AI as the Inference Provider and copy its ID (e.g. DeepSeek R1)
- Add a new model in Surf’s AI settings and configure it like below:
| Option | Value |
|---|---|
| Provider URL | https://router.huggingface.co/together/v1/chat/completions |
| Model ID | The model ID provided by Hugging Face, check their models page for available models |
| API Key | Your Hugging Face Access Token |
| Context Size | The maximum number of tokens for the context window, check the model page |
| Supports Vision | Whether the model supports vision tasks, check the model page |
| Supports JSON | Whether the model supports a JSON output format, smaller models usually don't |
You can also deploy your own Inference Endpoint on Hugging Face and use that with Surf. First checkout their guide on ho to create OpenAI compatible inference endpoint then add a new model in Surf’s AI settings and configure it like below:
| Option | Value |
|---|---|
| Provider URL | https://api-inference.huggingface.co/models/ |
| Model ID | The model ID provided by Hugging Face, check their models page for available models |
| API Key | Your Hugging Face Access Token |
| Context Size | The maximum number of tokens for the context window, check the model page |
| Supports Vision | Whether the model supports vision tasks, check the model page |
| Supports JSON | Whether the model supports a JSON output forma, smaller models usually don't |
In theory any provider that offers a OpenAI compatible chat completions API should work with Surf. In practice some providers are not fully compatible and can come with their own quirks. The only way to know for sure if a given provider works is by trying it out. Refer to the Configuration Options above on what information is needed.
If you do get a provider working please let us know on Discord or via E-Mail and we will add it to this list so others can easily set it up as well. If you run into issues let us know as well and we’ll see if we can add support for your provider.