providers.json

Provider configuration lives in a global file at ~/.posit/ai/providers.json, separate from the general Config File, ~/.posit/assistant/settings.json.

The provider configuration modal writes this file for you as you add and edit providers. This page is the reference for the file itself: its structure, its schema, and every setting it accepts.

Credentials never go in this file. Set API keys and tokens through the modal, which stores them separately.

For the list of supported providers, and for per-provider authentication and setup, see Providers.

Schema

The JSON schema lives at:

• https://assistant.posit.co/schemas/providers.schema.json

Posit Assistant points your file’s $schema at that URL when it first creates providers.json, and repairs the pointer if it is out of date. An editor with JSON Schema support then gives you completion, hover descriptions, and validation as you edit. Nothing reads the URL at run time, so provider configuration keeps working offline.

Settings reference

One table on providers.json Settings Reference lists every key the file accepts, with its type, default, and description. The table comes straight from the schema.

Common configurations

You can combine any of these in one file.

Choosing which models appear

Providers that discover their own models (through a /models endpoint) need none of this. The models block controls what shows up in the model picker. discovery decides whether to ask the provider at all, allow and deny filter what comes back, overrides patches metadata on models it returns, and custom declares models it does not.

{
  "providers": {
    "openai": {
      "models": {
        "allow": ["gpt-5.6", "gpt-5.6-mini"],
        "overrides": {
          "gpt-5.6": { "maxOutputTokens": 32000 }
        }
      }
    }
  }
}

Custom providers

Custom providers are experimental, and support varies by platform. RStudio gates the option behind Experimental Features in settings. Use the provider configuration modal where it is available. Otherwise, declare entries under providers.custom. Key each entry by a name of your choosing, which is also the display name, and give it a type:

{
  "providers": {
    "custom": {
      "acme-ai": {
        "type": "openai-compatible",
        "baseUrl": "https://ai-gateway.acme.com"
      }
    }
  }
}

The providers.custom.{name}.type row in the settings reference lists every type you can declare.

Only allow specific providers

Set providers.default.enabled to false to hide every provider, then enable just the ones you want:

{
  "providers": {
    "default": { "enabled": false },
    "anthropic": { "enabled": true },
    "openai": { "enabled": true }
  }
}

Route a provider through an enterprise proxy or gateway

Set a baseUrl for the proxy, plus any tenancy or routing headers it needs on every request:

{
  "providers": {
    "anthropic": {
      "baseUrl": "https://my-proxy.example.com/v1",
      "customHeaders": {
        "x-gateway-tenant": "team-42"
      }
    }
  }
}

Some providers need a version segment in that URL. See the baseUrl row in the settings reference.

customHeaders carries non-secret tenancy or routing metadata only. Assistant strips reserved headers such as Authorization and x-api-key, so use the provider’s credential field for anything that needs to authenticate. Four providers ignore customHeaders altogether: copilot, google-vertex, ollama, and lmstudio.

Redirect models that use different protocols

When a provider’s models do not all use the same API protocol, one baseUrl cannot redirect them all. Use endpoints to redirect every model on one protocol, or models.overrides to redirect a single model. Bedrock is the provider where this usually comes up:

{
  "providers": {
    "bedrock": {
      "endpoints": {
        "openai-chat": "https://my-proxy.example.com/bedrock/openai"
      },
      "models": {
        "overrides": {
          "openai.gpt-oss-120b": { "baseUrl": "https://my-proxy.example.com/gpt-oss" }
        }
      }
    }
  }
}

For each model, Assistant uses the first URL it finds in this order:

Order	Where the URL comes from	Applies to
1	models.overrides["<model-id>"].baseUrl	The single model named in the key
2	endpoints["<protocol>"]	Every model using that protocol, such as openai-chat for gpt-oss models or openai-responses for GPT-5.x
3	The endpoint the provider reports	Models with no override above
4	baseUrl	Models the provider reports no endpoint for

Claude models on Bedrock are the exception: they always go through the Anthropic Messages or Converse API using its AWS SDK endpoint, so none of the above applies to them.