Providers

Posit Assistant works with a range of model providers, though the set of providers and how you set them up vary by platform.

See Models for recommendations, cost comparisons, and the current Posit AI Pass catalog. This page covers connecting and configuring providers.

Custom providers aren’t listed in the table below, since they’re user-declared rather than a single built-in provider. See the custom providers section instead.

Available providers

A Preview badge means the provider is relatively new or hasn’t had extensive testing. It might work well, but behavior can change without notice. A provider with no badge is a broadly supported, production-ready path.

ProviderAuthentication
Posit AI PassSign in (OAuth)
Amazon BedrockAWS credentials or Workbench managed credentials
AnthropicAPI key
Databricks PreviewWorkspace URL + personal access token or service principal, or Workbench managed credentials
DeepSeekAPI key
GitHub Copilot (Positron only) PreviewSign in (OAuth)
Google GeminiAPI key
Google Vertex AI (Gemini Enterprise Agent Platform) PreviewGoogle Cloud credentials
LiteLLM (Positron 2026.09.0-128+) PreviewBase URL (API key optional)
LM Studio (Local)No credentials
Microsoft FoundryAPI key, Microsoft Entra ID, or Workbench managed credentials (Positron)
Ollama (Local)No credentials
OpenAIAPI key
OpenAI Compatible (Legacy)Base URL + API key (optional)
OpenCode PreviewAPI key
OpenRouter (Positron 2026.11+)API key
Portkey (Positron 2026.09.0-128+) PreviewBase URL + API key
Snowflake Cortexconnections.toml, API key, or Workbench managed credentials

OpenAI Compatible is legacy: it predates Custom providers and still works, but a custom entry with type: "openai-compatible" is the recommended path for a new OpenAI-compatible endpoint. See Custom providers below.

LiteLLM and Portkey need Positron build 2026.09.0-128 or newer. On earlier Positron releases — including every public 2026.08.x build — Assistant can’t register them at all: it deliberately keeps them unsupported there rather than writing a providers.json block that would trip the host’s own older, strict reader. RStudio, Standalone, Desktop, Connect, and the TUI have no such restriction.

Don’t see your provider listed? See Custom providers.

Configuring Providers

How you configure providers depends on your platform:

  • RStudio: Providers can be configured through the assistant settings UI.
  • Terminal (TUI): Press Ctrl+O to open the provider configuration screen, where you can sign in or enter credentials for supported providers.
  • Positron: On Positron 2026.11 and later, run Posit Assistant: Configure AI Providers or open it from the Accounts menu. This opens the AI Providers screen, where you select Connect next to a provider and sign in or enter its credentials. Earlier Positron builds use Authentication: Configure Language Model Providers instead, plus Posit Assistant: Configure Additional AI Providers for LiteLLM, Portkey, and OpenCode (on 2026.09.0-128 and newer). On those builds, custom providers stay in Positron’s own provider dialog.

For most API-key providers (Anthropic, OpenAI, Gemini, DeepSeek, OpenRouter, etc.), you just need an API key from the provider’s website. Provider Setup below covers each provider and anything extra it needs.

Anything the settings UI doesn’t cover is set in the global provider config file, providers.json. This includes proxy base URLs and custom headers, which models appear in the picker, disabling providers, declaring your own custom providers, and the connection settings a few providers need. See the settings reference for provider settings; preview agentEngines configuration is covered in Agent Engines.

The settings UI saves some settings to providers.json. If the file has a syntax error or a setting the schema doesn’t accept, or if a change would make it invalid, the save fails and says why: Positron lists each problem and offers to open providers.json, and other platforms show the error message. Fix the file, then save again.

Provider Setup

Posit AI Pass

Posit AI Pass is a managed service from Posit that gives you access to frontier LLMs through a single account. It’s the easiest way to get started — sign in once with no API keys to manage. See the Posit AI Pass documentation for account setup, available models, and billing.

Anthropic

Anthropic needs a Claude Console account with API access and an API key. You can also set the key with ANTHROPIC_API_KEY. To create a key:

  1. Sign in to or create an account for the Claude Console.
  2. Go to the API keys page and select Create Key.
  3. Fill in the details and select Add.
  4. Copy the key and keep it somewhere safe, such as a password manager.

A Claude Pro or Max subscription doesn’t work. Anthropic doesn’t include API usage in those plans, so signing in to Claude doesn’t give access to the API that Posit Assistant uses. You need Claude Console access and an API key, billed separately from any subscription. You can follow this feature request for updates on subscription sign-in.

OpenAI

OpenAI needs an API key from your OpenAI account, or set OPENAI_API_KEY. To send requests through a proxy, set a base URL or OPENAI_BASE_URL.

Amazon Bedrock

Amazon Bedrock uses AWS credentials rather than an API key. Your AWS account also needs access to the models you want to use. Configure access using the AWS CLI:

  1. Install the AWS CLI and run aws configure to set up your credentials.
  2. Ensure your IAM user or role has permissions to invoke Bedrock models (bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream) and to discover them (bedrock:ListFoundationModels and bedrock:ListInferenceProfiles). Without bedrock:ListInferenceProfiles, model listing still works in us-, eu-, and ap- regions via a legacy fallback, but other regions (such as ca-central-1 or me-central-1) require it and will show no models.

OpenAI gpt-oss and GPT-5.x models use Bedrock Mantle. The simplest setup is AWS’s AmazonBedrockMantleInferenceAccess managed policy. A custom least-privilege policy should include AWS’s documented Mantle inference permissions: bedrock-mantle:CreateInference, bedrock-mantle:GetProject, bedrock-mantle:ListProjects, and bedrock-mantle:ListTagsForResource, plus bedrock-mantle:ListModels for model discovery. On a model’s first use in an account it also needs aws-marketplace:Subscribe and aws-marketplace:ViewSubscriptions (scoped with aws:CalledViaLast = bedrock-mantle.amazonaws.com), unless an administrator has already enabled the model. Those Marketplace permissions are no longer needed after subscription; see AWS’s model access guide.

Set a region, a profile, or both, with aws.region and aws.profile in providers.json, or with the AWS_REGION and AWS_PROFILE environment variables. AWS_REGION on its own doesn’t connect Bedrock; pair it with a profile or with access-key environment variables. Bedrock uses the first region it finds: aws.region or AWS_REGION, then the region in the selected profile’s section of ~/.aws/config, then us-east-1. If you change that profile’s region while Posit Assistant is running, click Reload model list.

To use your default AWS profile, select it by name (aws.profile or AWS_PROFILE set to default), or set aws.region in providers.json. Posit Assistant reads a profile’s region only from a profile you select. You don’t need a profile if you use Posit Workbench managed credentials or the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

Posit Assistant honors AWS configured endpoints, so you can send Bedrock traffic through a VPC endpoint or proxy. For Bedrock Runtime (chats) it uses the first of these that is set: AWS_ENDPOINT_URL_BEDROCK_RUNTIME, AWS_ENDPOINT_URL, the bedrock_runtime entry of a [services] section referenced by the profile, then endpoint_url in the profile. Model listing does the same with AWS_ENDPOINT_URL_BEDROCK and bedrock. The profile is the one selected for Bedrock in Posit Assistant (aws.profile or AWS_PROFILE), and edits to ~/.aws/config take effect without a restart. Set AWS_IGNORE_CONFIGURED_ENDPOINT_URLS=true (or ignore_configured_endpoint_urls = true in the profile) to ignore all of them. OpenAI models (Mantle) always use Amazon’s address, because AWS defines no configured endpoint for them, so a network that blocks Amazon can still break those models. Configured endpoints can’t be combined with FIPS endpoints (see below): Posit Assistant reports an error until you remove one. Models with their own base URL, such as those from Posit Connect, ignore configured endpoints.

Posit Assistant calls models through cross-region inference profiles, with nothing to configure. It asks AWS which profiles your region can use and picks one per model: the profile for your region’s own geography (such as us. in us-east-1) first, then another regional profile, then a global. profile. A model with no inference profile in your region doesn’t appear in the model list.

If you use AWS SSO and your session expires, Posit Assistant shows a notification. In the graphical desktop and web apps (Standalone, Desktop, Connect, and RStudio) and the Positron extension it carries a Sign in again button — one click starts the refresh. In the TUI, the notification instead directs you to run aws sso login, then click Reload model list. The provider row shows the same Sign in again button. Either way, your credentials are refreshed in place — silently when a refresh token is cached, otherwise via a browser sign-in that shares the AWS CLI’s SSO cache (so aws sso login and Sign in again are interchangeable). When the browser runs on the same machine as Posit Assistant, sign-in uses the same PKCE flow as the AWS CLI: the browser rides your existing SSO session and redirects straight back, with no code to copy. The first sign-in with a new client registration asks you to allow access once; later sign-ins skip that page (the registration is shared with the AWS CLI’s cache, so consent given to aws sso login carries over). On remote or headless hosts (and whenever the local listener can’t start) it falls back to the device-code flow, which shows a code you can enter from any device’s browser. If no refresh can be attempted, Posit Assistant falls back to the configuration form.

Bedrock support is experimental in both AWS GovCloud regions: us-gov-west-1 and us-gov-east-1. Standard endpoints are used by default. To require AWS FIPS endpoints, set AWS_USE_FIPS_ENDPOINT=true, or set use_fips_endpoint = true in the selected AWS profile in your shared AWS config file. The environment variable takes precedence over the profile setting, including an explicit value of false. use_fips_endpoint is an AWS shared-config setting, not a providers.json field.

Mantle availability is model- and region-specific, so changing regions can legitimately change which gpt-oss and GPT-5.x models appear in the model picker.

AWS does not publish FIPS endpoints for Mantle. When FIPS is enabled, Posit Assistant skips Mantle discovery and does not offer or invoke Mantle models; other Bedrock models use the FIPS control-plane and runtime endpoints.

For Mantle Responses models, Posit Assistant sends store: false. This disables retrievable Responses storage, but it does not guarantee zero retention: AWS account/project retention policy is separate and should be configured to match your organization’s data-handling requirements.

Supported Mantle GPT models (the GPT-5.4, GPT-5.5, and GPT-5.6 families on the Responses route) offer provider-hosted web search in the us-east-1, us-east-2, and us-west-2 regions — the globe toggle appears automatically for eligible models, and answers include clickable citation links to the consulted sources. Web search needs bedrock-websearch:InvokeSearch and bedrock-websearch:InvokeFetch in addition to the Mantle inference permissions above; note that AWS’s AmazonBedrockFullAccess managed policy grants Search and Fetch but not external access. Posit Assistant does not probe these IAM actions during model discovery — if they are missing, the search request fails with the provider’s error.

By default, retrieval is restricted to AWS’s own web index and cache. The global webSearch.bedrock.externalWebAccess setting — or the Allow live external website access for Bedrock checkbox in the session HUD — additionally allows a cache miss to fetch the live external page, which widens the egress boundary and requires the bedrock-websearch:ExternalWebAccess IAM action. See Configuration File for the setting’s precedence and surfaces. Web search is never offered when FIPS endpoints are enabled, since AWS publishes no Mantle FIPS endpoint.

Google Vertex AI

📝 Preview

Google Vertex AI support is in preview. Not all features may work correctly.

Google Vertex AI, also called Gemini Enterprise Agent Platform (GEAP), uses Google Cloud Application Default Credentials. Install the Google Cloud CLI, then authenticate:

gcloud auth application-default login

When these credentials expire, Posit Assistant shows a notification with a Sign in again button — one click opens the provider configuration and re-runs the login for you (the Google Cloud CLI opens its own browser window, so this requires a browser colocated with the host). The provider row shows the same Sign in again button. If the CLI isn’t installed or the host is remote or headless, Posit Assistant falls back to the configuration form.

To use a service account instead, set GOOGLE_CLIENT_EMAIL and GOOGLE_PRIVATE_KEY, and optionally GOOGLE_PRIVATE_KEY_ID. When both are set, Posit Assistant uses them instead of Application Default Credentials, and Sign in again doesn’t apply.

Set your project and location with googleCloud.project and googleCloud.location in providers.json. location defaults to us-central1 if you leave it out.

Microsoft Foundry

Microsoft Foundry supports two authentication methods:

  • API key (default). Enter the key for your Foundry resource along with its base URL.
  • Microsoft Entra ID (experimental). Use ambient Azure credentials instead of an API key, for organizations that disable API-key authentication on their Foundry deployments. Authenticate with the Azure CLI (az login); managed identity, workload identity, and environment service principals also work through Azure’s DefaultAzureCredential chain. See Microsoft’s keyless authentication guidance for setup.

Entra mode is selected per deployment in the provider’s configuration form, or with azure.authMode in providers.json. The token scope defaults to https://cognitiveservices.azure.com/.default; set azure.scope (e.g. to https://ai.azure.com/.default) or azure.tenantId if your deployment requires it. No secret is stored in Entra mode — tokens are acquired and refreshed by the Azure credential chain.

You can paste the endpoint URL from the Foundry portal, including a deployment-style Azure OpenAI URL such as https://<resource>.openai.azure.com/openai/deployments/<name>/chat/completions?api-version=.... When you save, the provider form trims it to the /openai/v1 base URL. A base URL set by hand in providers.json or with MS_FOUNDRY_BASE_URL is used as written, so give it in the /openai/v1 form.

Foundry has no model discovery, so the model list shows only model-router, which routes each request to one of your deployments. To pick specific models, declare them under models.custom in providers.json, using each deployment’s name as its id.

In Positron on Posit Workbench, when an administrator has set up a Foundry endpoint, Posit Assistant uses the Foundry credentials Workbench provides, with nothing to set up.

⚠️ Admin-enforced Entra mode disables stored keys

An administrator can pin azure.authMode (or MS_FOUNDRY_AUTH_MODE) through enforced configuration. When Entra is pinned, any previously stored Foundry API keys and Positron sign-in sessions go inert by design — that is the enforcement — and the mode cannot be overridden from the user layer.

Snowflake Cortex

Posit Assistant can authenticate to Snowflake Cortex two ways:

  • From a connections.toml connection (recommended). If you already have a Snowflake connections.toml (used by the Snowflake CLI and Python connector), the configuration screen discovers its connections and lets you pick one. The credential is then acquired automatically based on the connection’s authenticator — external-browser single sign-on (EXTERNALBROWSER), key-pair JWT (SNOWFLAKE_JWT), a programmatic access token, or OAuth. The account host is derived from the connection’s account/host/region, so no base URL is needed.
  • With a token and base URL. Alternatively, enter a token directly along with a base URL pointing to your account’s Cortex endpoint.

In the provider form, pick a connection from the Connection list, or enter your Snowflake account identifier in Account Name and a programmatic access token in Bearer Token. The Cortex URL is built from the account identifier.

In Posit Workbench, when the connection in use is the workbench connection Workbench provides, Posit Assistant shows Snowflake Cortex as managed by Workbench. There’s nothing to set up, and you can’t edit or clear it from the provider form.

connections.toml is discovered from the standard locations ($SNOWFLAKE_HOME, ~/.snowflake, or the per-platform default directory). To point at a specific directory or pick a named connection, set snowflake.home and snowflake.connectionName in providers.json.

DeepSeek

DeepSeek needs a DeepSeek account with API access and an API key, or set DEEPSEEK_API_KEY.

Google Gemini

Google Gemini needs a Gemini API key, which you can create in Google AI Studio. You can also set GEMINI_API_KEY or GOOGLE_API_KEY.

OpenRouter

OpenRouter needs an OpenRouter API key, or set OPENROUTER_API_KEY. The built-in provider is available in Positron 2026.11 and later. On earlier Positron builds, add a custom provider with the OpenRouter type instead.

Custom providers

Use this for a provider Posit Assistant doesn’t ship built in — a self-hosted model server, an internal gateway, or any endpoint that speaks the OpenAI-compatible, Anthropic, LiteLLM, or Portkey wire protocol. You can also use it to connect several accounts on the same provider under names you choose.

To add one on the provider screen in RStudio, Standalone, Desktop, Connect, or Positron 2026.11 and later:

  1. Under Custom providers, select Add custom provider.
  2. Enter a Provider name. It appears in the model picker, and you can’t change it later.
  3. Select a Provider type. The type sets which connection fields you fill in next, the same ones as the built-in provider of that type.
  4. Fill in the connection fields, such as the API key and base URL, and select Add provider.

Select Edit on an entry to change its connection fields or credential. To change its name or type, delete the provider and add it again. Delete provider removes the entry and its stored credential. Disconnect clears only the credential and keeps the entry.

The TUI’s provider screen doesn’t manage custom providers, so declare them in providers.json there. Earlier Positron builds manage them in Positron’s own provider dialog.

You can also declare entries under providers.custom in providers.json. 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.

The built-in openai-compatible provider predates Custom providers and still works, but a custom entry with type: "openai-compatible" is the recommended path for an OpenAI-compatible endpoint going forward.

litellm and portkey are also supported custom types (both preview), for connecting to more than one gateway or presenting one under your organization’s own name — see LiteLLM and Portkey below for each gateway’s own credential and model-discovery contract.

A custom provider that needs no API key. When the endpoint authenticates another way — a local proxy that adds SSO credentials, say — a custom anthropic entry can declare that no API key is needed:

{
  "providers": {
    "custom": {
      "corp-sso-proxy": {
        "type": "anthropic",
        "baseUrl": "http://localhost:8787",
        "apiKeyOptional": true
      }
    }
  }
}

The entry is then ready from its baseUrl alone, and Assistant sends no Authorization or x-api-key header. Custom openai-compatible entries are key-optional already and need no flag. Like any providers.json key, an administrator can pin apiKeyOptional fleet-wide through POSIT_AI_PROVIDERS_ENFORCED.

⚠️ Older Positron builds do not recognize apiKeyOptional

Assistant itself always understands apiKeyOptional — its own config reader salvages unknown fields regardless of host or platform, so the entry works in the Assistant panel either way. Positron’s own provider management is different: it only understands the field once the host bundles the newer schema. On a host that has the newer schema but not yet the checkbox, the entry is just hidden from Positron’s native provider list until you update. On builds before 2026.09.0-128 — including every public 2026.08.x release — Positron’s own reader rejects the whole providers.json file instead, taking down its native provider list too. On current Positron builds, Assistant’s provider screen offers a checkbox for auth-less entries. Builds that still open Positron’s own provider dialog don’t manage custom providers in Assistant’s screen, so add the field to providers.json by hand there.

OpenCode

📝 Preview

OpenCode support is in preview. This integration is new and may change before general availability.

OpenCode offers two model services:

  • OpenCode Go — a subscription serving a curated set of open coding models.
  • OpenCode Zen — curated, benchmarked models, pay per request (with a free tier).

Posit Assistant lists OpenCode as a single provider entry with a Go/Zen product selector next to the API-key field, because one OpenCode workspace key works for both services. Pick the product, paste the key once, and save — the model list refreshes immediately to the selected service’s catalog. Switching products later reuses the saved key; there’s no need to paste it again. You can create a key at opencode.ai, enter it in the settings UI, or set the OPENCODE_API_KEY environment variable. No other configuration is needed — models are discovered automatically, and each model is reached over the wire protocol OpenCode documents for it (OpenAI Responses, Anthropic Messages, Gemini generateContent, or OpenAI Chat Completions).

The product choice defaults to Go. To change it outside the settings UI, set providers.opencode.product to "zen" in providers.json — this is also the way to choose Zen in the TUI, which has no product selector. The selector is disabled when an administrator has pinned the product or when an explicit baseUrl override is in effect, since the override makes the product choice inert.

If you subscribe to both products at once (a Go subscription plus Zen pay-per-request), use the built-in OpenCode entry and switch between them with the product selector — the saved key is reused on each switch. Configuring one product as an OpenAI Compatible custom provider instead is not supported: the session header OpenCode requires on inference requests is applied only by the built-in provider.

LiteLLM

📝 Preview

LiteLLM support is in preview. Not all features may work correctly.

Connect to a LiteLLM proxy and use any of the models it serves. A base URL is required (e.g., http://localhost:4000); an API key is optional and only needed when the proxy is protected by a master or virtual key.

Claude models served through the proxy — whether from Anthropic directly, Amazon Bedrock, or Google Vertex AI — keep full prompt caching and extended-thinking support. Posit Assistant sends explicit cache breakpoints with each request, so LiteLLM’s server-side automatic caching can be left disabled.

To connect to more than one gateway, or to present a gateway under your organization’s own name, declare custom providers with type: "litellm" under providers.custom — see Custom providers above.

📝 Custom LiteLLM entries and API keys

A hand-authored custom litellm entry in providers.json only supports a gateway that does not require a client key — the file itself never holds credentials, and customHeaders on a custom entry carries non-secret tenancy or routing metadata only; reserved authentication headers (Authorization, x-api-key) are ignored. On Node-backed graphical surfaces (Standalone, Desktop, Connect, RStudio), the provider configuration modal has an optional API key field when you add a custom LiteLLM entry, stored separately through the credential store. Outside the modal — a hand-authored entry, or one added through the TUI — a gateway protected by a master or virtual key must use this built-in provider instead.

📝 Terminal setup

The TUI configuration screen does not collect LiteLLM’s required base URL. Configure LiteLLM with LITELLM_BASE_URL (and LITELLM_API_KEY for a protected proxy), or set providers.litellm.baseUrl in the providers.json reference.

Each model the gateway serves is routed over its natural wire protocol. Claude models use LiteLLM’s Anthropic-shaped /v1/messages endpoint, preserving prompt caching and extended thinking as described above. OpenAI reasoning models (o-series, GPT-5.x) use /v1/responses and offer thinking-effort levels, with reasoning continuity preserved across turns. All other models (non-reasoning OpenAI models, Gemini, local models, etc.) use /v1/chat/completions; these get conservative capabilities without thinking-effort levels.

Administrators can override the routing in ~/.posit/ai/providers.json: set providers.litellm.models.overrides["<model-id>"].protocol to change the protocol for a single model, or set a connection-level providers.litellm.protocol to force every model through one protocol. Valid values are anthropic-messages, openai-chat, and openai-responses — bedrock-converse and google-generative cannot be routed through LiteLLM and are rejected.

Portkey

📝 Preview

Portkey support is in preview. Hosted Portkey has not yet been verified against the live service, and self-hosted gateway support depends on runtime-specific workarounds until a fixed gateway release ships.

Connect to Portkey: the hosted Portkey service, a corporate proxy in front of it, a Portkey hybrid or enterprise gateway, or a self-hosted Portkey OSS gateway. Portkey needs a base URL, an API key, and an API key type, which says what the key is:

  • Portkey API key ("portkey"): your Portkey API key. Use it for hosted Portkey, a proxy in front of hosted Portkey, or a hybrid or enterprise gateway.
  • Provider API key ("upstream"): the API key of a single upstream service (Anthropic by default). Use it for a self-hosted open-source gateway, which is stateless and forwards the key.

The settings UI configures a Portkey API key. A provider API key is a providers.json or environment setting: set providers.portkey.keyType to "upstream", or set PORTKEY_KEY_TYPE=upstream (see Connect Portkey to a self-hosted open-source gateway). If no key type is set, the base URL decides: https://api.portkey.ai means a Portkey API key, and any other URL means a provider API key.

SetupBase URLKey typeHow it connectsModels
Hosted Portkeyhttps://api.portkey.ai/v1PortkeyThe key is sent as x-portkey-api-key. /v1 is added if missing.Discovered from your Model Catalog, with IDs of the form @provider-slug/model
Proxy or hybrid gatewayYour gateway’s URLPortkeyThe key is sent only as x-portkey-api-key. The URL is used exactly as entered, so include /v1 if your gateway needs it.Discovered from <base URL>/models. Bare IDs and @provider-slug/model IDs both work.
Self-hosted OSS gatewaye.g. http://localhost:8787ProviderThe key is sent the way the upstream service expects. /v1 is added. Requests go to Anthropic unless you set an x-portkey-provider or x-portkey-config routing header.No discovery. Declare the models you use under providers.portkey.models.custom.

Discovery currently lists only the Claude models in a catalog; other model families are pending verification.

Posit Assistant checks the connection when you save it and again before each request:

  • A base URL is required. There is no default, because a defaulted URL could send a self-hoster’s provider key to hosted Portkey.
  • The api.portkey.ai host is valid only as https://api.portkey.ai on the default port, optionally with a path such as /v1.
  • Hosted Portkey accepts only Portkey API keys, so the provider key type with the hosted URL is an error.
  • The Portkey key type requires an API key.

Other URLs can use plain HTTP. In the settings UI, you can change the base URL without entering a saved key again, and a field set by an environment variable or an administrator is shown read-only. The settings UI writes keyType to providers.json only when it differs from what the base URL implies, because older Posit Assistant versions ignore a portkey block that sets it.

If the saved connection uses a provider API key, either because keyType is "upstream" or because a non-hosted base URL was saved without a key type, the settings UI keeps it and shows a notice. Select Use a Portkey API key instead to switch the connection to a Portkey API key, for example if you saved a proxy URL without a key type. The settings UI can’t switch back to a provider API key, and it doesn’t offer the switch when an environment variable or an administrator sets the key type.

📝 Terminal setup

The TUI configuration screen collects only Portkey’s API key, not its base URL or key type. Configure those with PORTKEY_BASE_URL and PORTKEY_KEY_TYPE, or set providers.portkey.baseUrl and providers.portkey.keyType in providers.json.

For hosted Portkey, no model configuration is needed. Enter your Portkey API key in the settings UI (the hosted base URL is prefilled), or set PORTKEY_API_KEY and PORTKEY_BASE_URL. In providers.json, the hosted connection is:

{
  "providers": {
    "portkey": {
      "baseUrl": "https://api.portkey.ai/v1"
    }
  }
}

For a proxy in front of hosted Portkey, or a hybrid or enterprise gateway, enter the gateway’s URL and your Portkey API key in the settings UI. In providers.json, set keyType to "portkey". Other headers your proxy needs go in customHeaders, which is plain text in providers.json, so don’t put secrets there. If the gateway doesn’t list models at <base URL>/models, declare them under models.custom, and add "protocol": "openai-chat" to a model if the gateway serves only the OpenAI chat-completions route:

{
  "providers": {
    "portkey": {
      "baseUrl": "https://proxy.example.com/portkey",
      "keyType": "portkey",
      "customHeaders": {
        "x-corp-team": "data-science"
      },
      "models": {
        "custom": [
          {
            "id": "claude-sonnet-4-6",
            "name": "Claude Sonnet 4.6",
            "maxContextLength": 200000,
            "supportsTools": true,
            "supportsImages": true,
            "supportsToolResultImages": true,
            "supportsWebSearch": false
          }
        ]
      }
    }
  }
}

For a self-hosted open-source gateway, which forwards one upstream service’s API key, set keyType to "upstream" in providers.json and declare your models. See Connect Portkey to a self-hosted open-source gateway for examples.

A self-hosted connection serves one upstream — multi-provider access through a single connection is what the hosted Model Catalog provides.

Custom providers.custom.<name> entries may also use type: "portkey" on Node-backed surfaces. That custom form is limited to a noncanonical self-hosted gateway or credential-injecting front proxy: declare bare upstream IDs in models.custom, normally set models.discovery to "off", and do not put secrets in customHeaders. There is no custom-ID environment mapping. providers.json itself never holds a credential, but the provider configuration modal on Node-backed graphical surfaces (Standalone, Desktop, Connect, RStudio) has an optional API key field for a custom Portkey entry, stored separately through the credential store; a hand-authored entry, or one added through the TUI, still needs a gateway that doesn’t require a client key. Use the built-in Portkey provider for hosted Portkey, which always requires a key. Custom Portkey entries have no keyType setting and keep the URL-based behavior, so a key for a proxy or hybrid gateway that expects a Portkey API key also needs the built-in provider.

Each model is routed over its natural wire protocol. Models with no declared protocol (including hosted Claude catalog models) use the Anthropic-shaped /v1/messages route, preserving prompt caching and extended thinking. A declared protocol of openai-chat routes over /v1/chat/completions, and openai-responses routes over /v1/responses (passed through for OpenAI upstreams, with reasoning continuity preserved across turns). To change the protocol for a single model, set providers.portkey.models.overrides["<model-id>"].protocol. Valid values are anthropic-messages, openai-chat, and openai-responses.

customHeaders is never a credential channel: the Portkey credential headers x-portkey-api-key and x-portkey-virtual-key can’t be set there. Enter the key in the settings UI or set PORTKEY_API_KEY. The routing headers x-portkey-provider and x-portkey-config apply to chat requests only; model discovery always queries the full catalog.

⚠️ Self-hosted gateway runtime

Portkey gateway 1.15.2 has runtime-dependent bugs: under Node.js 24 every streaming response fails, and under Bun responses are labeled Content-Encoding: gzip while the body is already decompressed, which breaks Node.js-based clients (including Posit Assistant) with an “incorrect header check” error. Until a fixed gateway release ships, place a proxy that strips the response Content-Encoding header in front of a Bun-run gateway, or run the gateway under Node.js 22.

Ollama

Ollama runs models locally on your machine. Install Ollama, pull a model, and you’re ready to go:

ollama pull llama3.2

No API key or credentials are needed. Posit Assistant talks to Ollama at http://localhost:11434 by default; if it’s running elsewhere, point at it with the OLLAMA_ENDPOINT environment variable or endpoint in providers.json.

LM Studio

LM Studio provides a local model server with a graphical interface. Install LM Studio, download a model, and start the local server. No API key or credentials are needed. Posit Assistant talks to LM Studio at http://localhost:1234/v1 by default; if it’s running elsewhere, point at it with the LMSTUDIO_ENDPOINT environment variable or endpoint in providers.json.

Databricks

📝 Preview

Databricks support is in preview. Not all features may work correctly.

Posit Assistant can discover and use models served by a Databricks workspace (Model Serving foundation models, external models, and custom serving endpoints). Every authentication method requires the workspace URL, such as https://dbc-example.cloud.databricks.com.

On every platform, including Positron, authenticate with a personal access token or a service principal. In Posit Workbench, Posit Assistant can also use the Databricks credentials Workbench manages. Signing in through your browser isn’t available yet. See the Databricks reference for setup, environment variables, credential priority, and model availability details. The workspace host also goes in providers.json, as databricks.host.

GitHub Copilot

📝 Preview

GitHub Copilot as a model provider is in preview and available only in Positron.

GitHub Copilot works as a model provider in Positron. You need a GitHub account with a Copilot subscription, or a seat assigned by an organization with Copilot Business. Students and teachers can use Copilot for free through GitHub Education.

This provider supplies models to Assistant’s built-in agent. GitHub Copilot Agent is a separate preview agent engine that runs Copilot’s own agent loop, with its own setup and host availability.

Copilot models appear in Posit Assistant once GitHub Copilot in Positron is signed in to GitHub, however you signed in, unless you disconnected the row (see below). If it isn’t signed in yet:

  1. Run Posit Assistant: Configure AI Providers from the Command Palette.
  2. Click Connect on the GitHub Copilot row and sign in to GitHub when prompted.

Connecting gives GitHub Copilot in Positron (chat and completions) access to that account.

Disconnect removes Copilot models from Posit Assistant until you click Connect again. It doesn’t sign you out of GitHub, and GitHub Copilot in Positron keeps working. To sign out of GitHub, use the Accounts menu or run Accounts: Manage Accounts. This signs you out of every Positron feature that uses your GitHub account, such as the Git and GitHub Pull Requests extensions.

GitHub Enterprise (GHE.com)

If your organization uses GitHub Enterprise on GHE.com instead of github.com, Copilot needs two extra settings. Your organization administrator must first turn on Copilot for your enterprise and assign you a seat.

  1. Set the github-enterprise.uri setting to your enterprise URL, for example https://octocorp.ghe.com.

  2. Run Preferences: Open User Settings (JSON) and add authProvider under github.copilot.advanced:

    "github.copilot.advanced": {
      "authProvider": "github-enterprise"
    }

    Positron marks this as an Unknown Configuration Setting. That’s expected, and you can ignore it.

  3. Save the file. When the prompt to sign in to GitHub appears, select it and finish signing in in your browser. If no prompt appears, restart Positron.

For more detail, see GitHub’s guide to authenticating to GitHub Copilot on GHE.com.

Environment Variables

Provider credentials can also be set via environment variables. Environment variables take precedence over file-based configuration.

Environment variables must be set before the host environment (RStudio) starts, so for day-to-day IDE use the settings UI or providers.json reference is usually more practical. Environment variables are most useful for the TUI, CI/CD pipelines, and containerized deployments.

VariableDescription
ANTHROPIC_API_KEYAPI key for the Anthropic provider
ANTHROPIC_BASE_URLCustom base URL for the Anthropic provider
OPENAI_API_KEYAPI key for the OpenAI provider
OPENAI_BASE_URLCustom base URL for the OpenAI provider
GEMINI_API_KEYAPI key for the Gemini provider
GOOGLE_API_KEYAPI key for the Gemini provider, used when GEMINI_API_KEY is not set
GEMINI_BASE_URLCustom base URL for the Gemini provider
OPENAI_COMPATIBLE_API_KEYAPI key for the OpenAI Compatible provider
OPENAI_COMPATIBLE_BASE_URLCustom base URL for the OpenAI Compatible provider
MS_FOUNDRY_API_KEYAPI key for the Microsoft Foundry provider
MS_FOUNDRY_BASE_URLCustom base URL for the Microsoft Foundry provider
MS_FOUNDRY_AUTH_MODEFoundry authentication mode: apikey (default) or entra
MS_FOUNDRY_ENTRA_SCOPEEntra token scope for Foundry (default https://cognitiveservices.azure.com/.default)
MS_FOUNDRY_TENANT_IDAzure tenant ID for Foundry Entra authentication
OPENROUTER_API_KEYAPI key for the OpenRouter provider
DEEPSEEK_API_KEYAPI key for the DeepSeek provider
DEEPSEEK_BASE_URLCustom base URL for the DeepSeek provider
SNOWFLAKE_TOKENAPI token for Snowflake Cortex
SNOWFLAKE_BASE_URLCustom base URL for the Snowflake Cortex provider
DATABRICKS_HOSTWorkspace URL for the Databricks provider
DATABRICKS_TOKENPersonal access token for the Databricks provider
DATABRICKS_CLIENT_IDService-principal OAuth client ID for Databricks
DATABRICKS_CLIENT_SECRETService-principal OAuth client secret for Databricks
DATABRICKS_AUTH_TYPESet to oauth-m2m to use the service principal when DATABRICKS_TOKEN is also set
DATABRICKS_CONFIG_PROFILEProfile to read from the Posit Workbench managed Databricks configuration file (default workbench)
AWS_REGIONAWS region for the Bedrock provider
AWS_PROFILEAWS profile for the Bedrock provider
AWS_USE_FIPS_ENDPOINTUse AWS FIPS endpoints for Bedrock; equivalent to use_fips_endpoint in the selected AWS shared-config profile
AWS_ENDPOINT_URL_BEDROCK_RUNTIMECustom endpoint for Bedrock chats (also AWS_ENDPOINT_URL_BEDROCK for model listing, AWS_ENDPOINT_URL for both)
AWS_IGNORE_CONFIGURED_ENDPOINT_URLSSet to true to ignore all AWS configured endpoints
AWS_ACCESS_KEY_IDAWS access key ID for the Bedrock provider
AWS_SECRET_ACCESS_KEYAWS secret access key for the Bedrock provider
AWS_SESSION_TOKENAWS session token for the Bedrock provider
GOOGLE_CLOUD_PROJECTGoogle Cloud project for the Vertex AI provider
GOOGLE_CLOUD_LOCATIONGoogle Cloud location for the Vertex AI provider
GOOGLE_CLIENT_EMAILService-account email for the Vertex AI provider
GOOGLE_PRIVATE_KEYService-account private key for the Vertex AI provider
GOOGLE_PRIVATE_KEY_IDService-account private key ID for the Vertex AI provider (optional)
POSITAI_BASE_URLCustom base URL for the Posit AI Pass provider
OLLAMA_ENDPOINTEndpoint URL for Ollama
LMSTUDIO_ENDPOINTEndpoint URL for LM Studio
LITELLM_API_KEYAPI key for the LiteLLM provider
LITELLM_BASE_URLBase URL for the LiteLLM provider
PORTKEY_API_KEYAPI key for the Portkey provider: a Portkey API key, or the upstream provider’s key for a self-hosted gateway (see PORTKEY_KEY_TYPE)
PORTKEY_BASE_URLBase URL for the Portkey provider (required)
PORTKEY_KEY_TYPEWhat PORTKEY_API_KEY is: portkey or upstream (inferred from the base URL when unset)
⚠️ API keys

Never commit API keys to version control. Use environment variables or a secrets manager for sensitive credentials.