Provider connections
Configure endpoints, protocol types and credentials for your model accounts.
In this topic
A provider connection tells Mellow where a model service lives, how to authenticate and which request format it understands. It can point to a hosted service or a compatible server on your own network.
Choose the connection matching the service's protocol. A correct URL with the wrong API type can pass a basic network check and still fail every chat request.
Adding a provider
Open Settings → Providers. Choose a preset when one matches your service, or enter a custom connection. Supply the account or API key required by that route, then connect and refresh the model list.
Before changing an agent's default model, send a short message through the new provider. Test attachments and tools separately if your workflow needs them.
API format types
Mellow's provider configuration distinguishes these request families:
| Type | Request family | When it matters |
|---|---|---|
| OpenAI Compatible | Chat Completions | Compatible local servers and gateways |
| Open Responses | Responses | Services implementing that contract |
| OpenAI Codex | ChatGPT/Codex authenticated Responses route | Account sign-in rather than an ordinary API-key connection |
| Anthropic | Messages | Anthropic-format message and tool exchange |
| Google Gemini | Model-specific generation | Gemini model naming and content format |
| Azure OpenAI Foundry | Azure's configured OpenAI-compatible route | Resource address and deployment configuration |
| Mellow Agent | Native agent run | Remote agent execution rather than raw model inference |
These names describe supported adapters. They do not imply that a subscription grants access to every adapter or model.
Signing in with OAuth
Use the provider's sign-in action and complete its browser flow. Return to Mellow, reconnect if necessary, and check that discovery succeeds. A browser session alone is not the stored token set used by the provider connection.
If Mellow reports Missing ChatGPT/Codex sign-in tokens, sign in with ChatGPT for that connection and retry it. Pasting an unrelated API key or selecting a different endpoint format will not repair missing sign-in tokens.
Configuration options
| Setting | Purpose | Common mistake |
|---|---|---|
| Name | Identifies the connection in Mellow | Giving different endpoints identical names |
| Host and protocol | Select the destination and transport | Including a path where only a host is expected |
| Port | Overrides the transport default | Using the website port instead of the API port |
| Base path | Prefix for that service's API | Repeating /v1 or another prefix |
| Authentication | Selects key or supported sign-in | Mixing subscription sign-in with API-key access |
| Enabled | Makes the connection usable | Leaving a repaired connection disabled |
| Auto-connect | Reconnects through the provider lifecycle | Assuming it can fix an expired credential |
| Timeout | Limits how long requests wait | Hiding a protocol error behind a very long timeout |
| Manual model IDs | Provides explicit IDs when appropriate | Inventing IDs not accepted by the server |
| Custom headers | Supplies service-specific metadata | Storing secret values as ordinary visible headers |
Use the endpoint shown in the connection summary to check the assembled address. Protocol adapters append their own request paths; the base path must match that adapter's expectations.
Custom headers
Only add headers required by your service. Mark credentials as secret where supported, and inspect diagnostic exports before sharing them. Mellow classifies common authentication headers as sensitive, but a custom header name still deserves review.
Using remote models
Select the connected provider and an advertised model in the composer. A provider can be reachable while a particular model is unavailable to your account. Refresh discovery after changing entitlements, deployments or the server's model configuration.
Capabilities vary by model and adapter. Validate text first, then image input, streaming and tools as separate checks. A successful text response does not prove all features of another provider's SDK are supported.
Provider metadata and multimodal input
Model metadata can describe supported modalities and options. If a control is absent, do not force it into a request based on another model's example. Manual model entries are useful for servers without discovery, but they cannot make an unsupported model or modality available.
Prompt caching
Caching behavior belongs to the provider and request format. Do not assume repeated prompts are free or cached. Inspect the usage information supplied for that request when evaluating cost or cache effectiveness.
Connection states
| State | What has been established |
|---|---|
| Disabled | The saved connection is not active |
| Connecting | Mellow is checking the connection |
| Connected | The connection check succeeded; test the selected model next |
| Authentication required | Credentials are absent, expired or rejected |
| Failed | Inspect the error to separate transport, discovery and request failures |
Refreshing is appropriate after correcting a URL or credential. Repeated refreshes cannot fix a wrong API family or an unavailable account entitlement.
Provider-specific setup decisions
For a hosted API, use the endpoint and credential issued for that API product. For ChatGPT sign-in, use the dedicated account flow. For a local server such as an OpenAI-compatible model host, confirm it is running and exposing the expected API on the configured address.
For an Azure deployment, preserve its resource and deployment requirements. For a gateway, verify its advertised protocol rather than selecting an adapter solely because it offers a familiar model name.
A remote Mellow agent executes on its own host. Its tools, files and provider configuration belong to that host; it is not simply a new model downloaded to this Mac. See Devices and Mobile.
Troubleshooting
| Error pattern | Next step |
|---|---|
| Missing sign-in tokens | Complete the dedicated sign-in and retry |
| Unauthorized | Check credential type, expiry and account |
| Not found | Check base path, protocol and model/deployment ID |
| Connected with no models | Inspect discovery; use documented manual IDs only if supported |
| Works locally but not from another device | Check host address, server binding and network reachability |
| Text works but tools fail | Test adapter/model tool support and agent permissions |
| Request times out | Check server logs and workload before raising timeout |
Managing providers
Give each connection a useful name. Disable a connection when you want to keep its configuration without using it; remove it when you no longer need the saved setup. After changing or removing one, update agents and conversations that depended on it.
Provider credentials and Cloud workspace sessions are separate. Signing out of one does not prove the other has been removed. See Cloud workspaces for workspace-specific session management.
Continue exploring · Models, voice and mediaApple’s on-device model →Check Foundation availability, choose suitable tasks and handle its context limits.