Skip to main content
Each user configures their own model providers under Settings → Providers. Nothing is shared between users, and credentials never leave the control plane.

​
Add a provider

A provider is any endpoint implementing the OpenAI API surface.
1

Enter the base URL

Use the URL that has /chat/completions and /models beneath it, usually ending in /v1.
2

Add the API key

The key is encrypted with SETTINGS_ENCRYPTION_KEY before storage. It is write-only: the API returns a hasApiKey flag and never the value itself.
3

Add custom headers if needed

Some gateways require extra headers, such as OpenRouter’s HTTP-Referer and X-Title.
Custom headers are different from API keys. Because they must remain editable in the UI, GET /api/providers decrypts them for the authenticated owner. Treat header values as secrets visible to any client logged in as that user.
4

Test the connection

Test connection requests <base URL>/models through the outbound guard. This validates the URL, the key, and network reachability in one step.

​
Add models

A provider holds any number of models. Each needs:
​
string
required
The exact identifier the provider expects, such as gpt-4o-mini or anthropic/claude-sonnet-4.
​
string
required
The label shown in the model picker.
​
integer
required
Total token limit for the model. Used to decide when to trim context.
​
integer
required
Upper bound on a single response. Setting this above the provider’s real limit causes request errors.

​
Default model rules

Exactly one model per user is the default, enforced by the models_one_default_per_user partial unique index.
  • Make default releases the current holder before setting the new one, because the index rejects the opposite order.
  • Deleting or disabling the default model, or the provider that owns it, automatically promotes the oldest remaining enabled model.
  • A user therefore always has a usable default as long as one enabled model exists.

​
The outbound request guard

Every outbound call is checked before it is made. By default the guard rejects:
  • Non-HTTPS URLs
  • URLs containing embedded credentials
  • Private, loopback, and link-local addresses
  • Cloud metadata endpoints
  • Redirects to any of the above
No configuration needed. Public HTTPS endpoints pass the guard.

​
Troubleshooting

The guard rejected the URL. Confirm it is HTTPS and publicly resolvable, or enable ALLOW_PRIVATE_EGRESS for an internal endpoint.
The stored key is wrong or lacks access to the requested model. Keys are write-only, so re-enter it rather than trying to read it back.
The base URL is probably missing or duplicating its version segment. The application appends /chat/completions, so the base URL should end at /v1.
The configured context window exceeds the model’s real limit. Lower it to the provider’s documented value.
If SETTINGS_ENCRYPTION_KEY changed, stored credentials cannot be decrypted. Restore the original key or have users re-enter their credentials.

​
Backup implications

Provider credentials are encrypted in the database with the installation key. The database and SETTINGS_ENCRYPTION_KEY form a single recovery unit; a database restore without the matching key yields unreadable credentials.

Backup and restore

What to back up and how to validate a restore.