Connect a coding agent to custom models

Connect your agent

Every agent below needs the same three values:

Value	What to enter
Base URL	`https://gateway.ngrok.ai/v1`
API key	Your access key, such as `ng-xxxxx-g1-xxxxx`
Model	Your `provider:model` name, such as `ollama:llama3.2`

OpenCode
Zed
Pi
Cursor
Anything else

OpenCode is a terminal coding agent.Add the gateway as a provider in ~/.config/opencode/opencode.json, or in an opencode.json beside your project:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ngrok": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ngrok AI Gateway",
      "options": {
        "baseURL": "https://gateway.ngrok.ai/v1",
        "apiKey": "ng-xxxxx-g1-xxxxx"
      },
      "models": {
        "ollama:llama3.2": { "name": "Llama 3.2 (via ngrok)" }
      }
    }
  }
}

Replace these required fields:

apiKey with your ngrok.ai access key
Keys in the models field with your full provider:model name and display-friendly name

Then test it with a prompt, replacing ngrok/ollama:llama3.2 with your model:

opencode run -m "ngrok/ollama:llama3.2" "Explain quantum entanglement like I'm 10."

Zed is a code editor with a built-in agent panel.Add the provider to your settings.json:

{
  "language_models": {
    "openai_compatible": {
      "ngrok": {
        "api_url": "https://gateway.ngrok.ai/v1",
        "available_models": [
          {
            "name": "ollama:llama3.2",
            "max_tokens": 131072
          }
        ]
      }
    }
  }
}

Replace these required fields:

name with your provider:model name
max_tokens with your model’s context window

Next, add your ngrok.ai access key through the Zed UI. Open the command palette, run agent: open settings, select LLM Providers, then Configure, find ngrok in the provider list, paste your access key, and hit Enter.Create a new Zed Agent Thread, pick your custom model from the selector at the bottom of the agent panel’s message editor, and test it:

Explain quantum entanglement like I'm 10.

Pi is a terminal coding agent.Add the gateway as a provider in ~/.pi/agent/models.json:

{
  "providers": {
    "ngrok": {
      "baseUrl": "https://gateway.ngrok.ai/v1",
      "apiKey": "ng-xxxxx-g1-xxxxx",
      "api": "openai-completions",
      "models": [
        { "id": "ollama:llama3.2" }
      ]
    }
  }
}

Replace these required fields:

apiKey with your ngrok.ai access key
id with your full provider:model name

id is the only field a model entry needs, though you can add name, contextWindow, and maxTokens to label it and track context accurately.Then test it with a prompt:

pi --provider ngrok --model "ollama:llama3.2" -p "Explain quantum entanglement like I'm 10."

Cursor is a code editor with a built-in agent. It reaches custom models by overriding the base URL of its OpenAI provider, so the gateway stands in for OpenAI.

This needs a paid Cursor plan. Free plans can only use Cursor’s Auto model and can’t select a named model, which is what a model you add yourself is.

Open Cursor Settings, go to Models, and expand API Keys:

Turn on OpenAI API Key and paste your ngrok.ai access key. The field is labeled OpenAI, but Cursor sends the key to whatever endpoint you configure below.
Turn on Override OpenAI Base URL and enter https://gateway.ngrok.ai/v1. Keep the /v1 suffix: Cursor appends /chat/completions to whatever you enter.
Select + Add model, enter your full provider:model name, such as ollama:llama3.2, and enable it.
Select Verify to confirm the gateway answers.

Pick your model in the chat model selector and test it:

Explain quantum entanglement like I'm 10.

The base URL override is global. While it’s on, Cursor routes its other OpenAI-model traffic to the gateway too, which fails for models your access key can’t reach. Turn the override off to go back to Cursor’s own models.

Expect chat, not the whole editor. Three Cursor behaviors limit how far a custom model reaches:

Tab completion always uses Cursor’s built-in models. It never reaches your endpoint.
Agent and Edit also rely on Cursor’s own models, so Cursor may refuse them while a custom API key is set and ask you to disable the key.
Where agent runs do work, Cursor’s tool definitions over an overridden base URL aren’t strictly OpenAI-shaped, so tool calls can fail against a self-hosted model even when plain chat succeeds.

Want us to add instructions for a specific coding agent? Log in to app.ngrok.ai, click Give feedback, and let us know what you’d like to see.

Any tool that accepts an OpenAI base URL and key theoretically works the same way. Set the base URL to https://gateway.ngrok.ai/v1, the key to your access key, and the model to your provider:model name.Name the model yourself rather than picking it from a list. A tool that populates its model picker by calling the gateway won’t find your models.The gateway serves these endpoints, so tools that use the Responses API or the Anthropic Messages API work too:

Endpoint	Format
`/v1/chat/completions`	OpenAI
`/v1/responses`	OpenAI
`/v1/messages`	Anthropic

/v1/messages only reaches providers that support the Anthropic Messages surface. Ollama, LM Studio, and vLLM expose the OpenAI surface, so send requests for a model you run yourself to /v1/chat/completions or /v1/responses.

For SDK-level examples, see Use with other SDKs.

Concepts

Getting Started With

SDKs

Guides

Observability

Examples

Reference

API Reference

Connect a coding agent to custom models

What you’ll need

Getting started

Next steps

​What you’ll need

​Getting started

​Next steps

What you’ll need

Getting started

Next steps