A provider connection identifies an account or endpoint. A model group chooses a model from that connection, its request settings, and any fallback models. Agents select model groups.
You can keep separate work and personal connections to the same provider, or use different endpoints for different groups. Each connection has a unique handle such as openai-work. Model groups reference that handle.
Add a connection
Administrators manage global model connections under Administration → Providers. The setup wizard uses the same provider editor.
- Choose a provider brand and click Add connection.
- Set a unique Connection handle and any required endpoint or region fields.
- Choose an Authentication method. Depending on the provider, you can enter a key, reference a server environment variable, use a saved credential, sign in to an account, or use the server's AWS credentials.
- Wait for connection validation or complete the sign-in flow. Changing the connection or credential requires fresh validation.
- Save the settings, then restart when prompted to activate the configuration.
The connection shows its active authentication source and the groups that use it. Move those groups and their fallbacks to another connection before deleting one they reference. New keys and account tokens are stored encrypted in the database. Saved credential lets compatible connections share an authorized managed credential. Logging out a shared credential affects every connection using it.
Environment-variable references keep the secret in the server environment. The variable must exist inside the Frona container; putting it in a host .env file alone does not forward it. See Environment Variables.
Account sign-in
The provider editor offers these interactive connections:
| Provider brand | Authentication | Flow |
|---|---|---|
OpenAI (openai) | ChatGPT subscription | Click Connect, open the provider login page, and enter the displayed device code. Enable device login in your account or workspace settings if requested. |
GitHub Copilot (github-copilot) | Sign in | Click Connect and authorize the displayed device code with GitHub. |
OpenRouter (openrouter) | Connect OpenRouter | Authorize Frona in the provider page, paste the returned authorization code into Login completion code, then click Complete login. |
Frona polls device login status while the attempt is pending. You can cancel an attempt or start again after it expires. Successful authentication does not guarantee access to every model or available quota; those are checked when making requests.
ChatGPT account credentials use the Responses protocol. GitHub Copilot selects its supported protocol per model. OpenRouter sign-in creates an API key billed to your OpenRouter account; it does not provide subscription access.
Managed credentials refresh when needed before use. Log out revokes the stored credential immediately for subsequent use, including active provider configurations. New connection settings still require the indicated restart.
Azure and Bedrock
Azure OpenAI requires the resource endpoint and an API key. Enter the exact Azure deployment name as the model ID. The adapter supports Chat Completions; the credential check does not discover your deployment names. Microsoft Entra authentication is not supported in this release.
Amazon Bedrock uses Converse and supports either a bearer API key or the server's AWS credential chain. Set a region and, if needed, a named AWS profile. An explicit bearer key does not fall back to an unrelated AWS identity when authentication fails. If live discovery is unavailable, enter the model or inference-profile ID manually.
See the Azure and Bedrock YAML examples.
Configure model groups
Open Administration → Models and select a connection and model for each group. Keep a primary group for the default agent. Other groups can specialize in coding, reasoning, memory, or another task.
The selector combines live provider results with catalogue metadata and saved models. You can enter a model ID manually when it is absent from discovery. A saved or catalogued model is not proof that the current credential can access it.
Choose a supported Protocol, then configure the settings shown for that connection, model, and protocol. Unsupported settings are identified so you can remove them. Native JSON fields belong in the separate Custom request parameters section; see the parameter reference.
For connections using the OpenAI brand, the default protocol is Responses. Use Chat Completions (api: completions in YAML) for endpoints that need it. Existing api: chat_completions settings remain accepted.
Add fallbacks in the order Frona should try them. Each fallback can use a different connection and its own model parameters. Streaming can fall back before any output is emitted; after output begins, a failure is reported without switching models mid-response.
Catalogue availability
Production images bundle validated model and parameter catalogues. Frona can start from a valid bundled or cached copy, refreshes sources in the background, and retains valid data when a refresh fails. Settings show stale-source warnings and allow retrying metadata or credential loading.
Live model discovery and credential validation are separate operations. A validated connection may still need a manually entered model, and a visible catalogue entry may not be available to your account. Frona only offers protocols supported by its installed adapters.
Next steps
- Config File. Named connections and model-group YAML.
- Managing Secrets & API Keys. Credentials granted to agent tools.
- Troubleshooting. Connection, model, and configuration failures.