Skip to main content
Sign in to Qualia to use your account’s models, then add your own provider keys if you want a provider’s requests to skip Qualia’s servers. You configure provider keys in Settings > Models > Provider access.

Sign in to Qualia

The first time you open the desktop app, choose a Continue with option, or enter your work email and choose Continue with SSO. Qualia opens your browser to finish. When you are done, choose Continue to Qualia to return to the app. Signing in creates your account if you are new. In Qualia Cloud, the sign-in page offers the same options. After you sign in, Qualia returns you to the page you were opening. If sign-in fails, choose Return to login to retry. To sign in or out later on desktop, open Settings and choose the account menu at the bottom of the sidebar. Then choose Sign in or Sign out. You can also sign in from the notice above chat. Signing in on desktop saves a key on this device, which Settings lists as Qualia sign-in key. You don’t need to enter it yourself. It starts with qd_live_, like an enterprise activation key, but it belongs to your own sign-in.

Activate an enterprise deployment

On an enterprise deployment, choose enter your activation key on the sign-in screen. Paste the key your administrator gave you and choose Activate. Activation needs internet access. If Qualia rejects the key, ask your administrator to check it.

Sign in to the quad-code terminal app

In quad-code, the Qualia terminal app, press Enter on the welcome screen to sign in through your browser. Later, use Ctrl+K > Account. To sign in from another device, press P and paste the sign-in token back into the terminal. Press M to manage sessions.

Manage sessions

Each sign-in to the desktop app or the qualia CLI is a session. To review them, choose Manage sessions from the account menu at the bottom of the Settings sidebar. This opens Security in Qualia Cloud Settings. Security lists this browser and each desktop and terminal app session, with when it was last active. Choose Sign out beside a session to end its access, or Sign out all to end every one. Don’t leave a session you don’t recognize signed in, because it can use your account’s models.

Use your own provider keys

Model calls go through Qualia’s servers by default. To use your own key for OpenAI, Anthropic, or Google Gemini, open Settings > Models > Provider access and choose that provider’s auth mode:
  • Qualia keeps the provider on your Qualia account, or on your activation on an enterprise deployment.
  • API key or custom endpoint calls the provider with your own key, a custom endpoint, or both.
  • Azure Entra ID and Azure (API key) call Azure deployments. See Azure endpoints.
You set each provider separately, so you can bring your own Anthropic key and keep OpenAI on Qualia’s servers. A status line above each provider shows which route is in effect. To get a Google Gemini key, open Google AI Studio.

Custom provider endpoints

To route a provider to an OpenAI-, Anthropic-, or Gemini-compatible endpoint, choose API key or custom endpoint and set that provider’s base URL. Add the provider API key if the endpoint needs one.
  • Leave the base URL blank to use the provider’s default endpoint.
  • Use an http or https URL, and include any required path prefix, such as /v1 for OpenAI-compatible endpoints.
  • Only use an endpoint you trust with your provider API key.
  • On a shared deployment, enter your own provider API key alongside a custom base URL.
For a basic Bedrock-compatible gateway that accepts API key authentication, enter the matching provider API key and the gateway’s base URL.

Model ID aliases

A self-hosted endpoint sometimes serves a model under a different ID than Qualia’s catalog uses. For example, it might serve claude-fable-5 as claude-fable-5-CAVEAT[1m]. Under the provider, choose Add alias under Model ID aliases and map the catalog model to the ID your endpoint expects. Requests to your endpoint use the alias, while the model picker still shows the catalog model. Aliases never apply when requests route through Qualia’s servers.

Custom headers

Some gateways in front of a provider, such as Portkey or Azure API Management, need extra HTTP headers. To add them, choose Add header under Custom headers, enter each name and value, and choose Save headers. Every request to that provider’s endpoint then carries those headers.
  • After you save, Settings shows only the header names. Choose Replace headers to enter new values, or Clear to remove them.
  • You can’t set Host, Content-Length, Transfer-Encoding, or Connection.
  • Custom headers never apply when requests route through Qualia’s servers.
Custom headers don’t change how Qualia sends the API key. If your gateway expects the key as a bearer token instead of Anthropic’s x-api-key header, set Anthropic API key header to Authorization: Bearer. Qualia then sends the key only as Authorization: Bearer [YOUR_KEY]. For example, to use Anthropic through a Portkey gateway:
  1. Paste the Portkey key as the Anthropic API Key.
  2. Set Anthropic API key header to Authorization: Bearer.
  3. If your gateway routes by provider, add an x-portkey-provider: [PROVIDER_SLUG] custom header.

Short-lived keys from a command

Some gateways, such as TrueFoundry, issue keys that expire after a few hours, so a saved key stops working. Instead, enter a shell command that prints a key in OpenAI API key command, Anthropic API key command, or Google Gemini API key command. For example: timeout 30 llmgw get token. These fields appear in API key or custom endpoint mode.
  • Qualia runs the command to get a key, and again whenever your endpoint rejects the key.
  • The command’s key replaces the saved API key. The base URL, API key header, model ID aliases, and custom headers still apply.
  • The command must print only the key on standard output and exit with status 0 within 60 seconds. On a remote backend, it runs on the remote machine.
  • If the command fails, chat shows its exit status and error output.
  • A helper written for Claude Code’s apiKeyHelper setting works unchanged.
You can’t set an API key command in Qualia Cloud or on a shared self-hosted deployment. For a TrueFoundry gateway:
  1. Set the base URL to your gateway’s /api/llm endpoint, such as https://[TENANT].truefoundry.cloud/api/llm.
  2. Set Anthropic API key header to Authorization: Bearer.
  3. Add a Model ID alias for each model you use, because TrueFoundry names models [PROVIDER_ACCOUNT]/[MODEL]. For example, map claude-sonnet-5 to my-anthropic/claude-sonnet-5.

Azure endpoints

For Azure OpenAI or Anthropic models in Azure Foundry, set the auth mode to Azure Entra ID and enter the Azure endpoint URL. If your Azure deployment uses a key instead, choose Azure (API key) and paste the key alongside the endpoint URL. Azure Entra ID uses credentials already on the host, such as a managed identity, an Azure CLI login, or service-principal values (AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET). Leave Azure Entra scope blank unless your administrator gives you a custom scope.

Manage saved keys

  • Settings shows a saved key as a masked hint. You can’t reveal the saved value, and in Qualia Cloud your keys stay private to your account.
  • To replace a key, focus its field and enter the new one. Qualia saves it automatically.
  • To remove a key, choose its Clear credential button.

Where your keys are stored

On desktop, Qualia encrypts saved keys and protects them with your operating system’s keychain. If no keychain is available, Qualia saves them in a file only your user account can read, and a notice below the titlebar tells you. If saved keys stop working because the keychain is locked, see Keychain locked. In Qualia Cloud, Qualia encrypts your keys and keeps them private to your account.

Import keys from this computer

When you connect the desktop app to a remote backend that has missing keys or different preferences, a banner offers Review. In Import settings from this computer, review the proposed changes and choose Import. Qualia never shows key values in the dialog. Existing remote keys stay unchanged. To connect to a remote backend, see Getting started.

Fix common problems

Invalid key errors

  • Check that you copied the key without extra spaces.
  • Check that the key is active in the provider’s dashboard.
  • Check that you haven’t exceeded the key’s usage limits.
If Qualia reports a sign-in error, choose Sign in from the account menu at the bottom of the Settings sidebar. In quad-code, use Ctrl+K > Account.

Out of credits

Qualia names the account that ran out, so you know who can fix it.
  • If you use your own provider key, the message points at your provider account. Add credits or update billing with that provider, then retry.
  • If you don’t use your own key, the message points at your Qualia plan. See Account usage limits and Change your plan.
  • If the message says the problem is on Qualia’s side, your account is fine. Try another model or contact support.

Model not available

  • If chat says Couldn’t load models, choose Retry to reload the list.
  • Check your sign-in in the account menu at the bottom of the Settings sidebar.
  • Check your provider credentials in Settings > Models > Provider access.
  • Some models require specific account access or waitlist approval.

Keychain locked

On desktop, Qualia protects saved keys with your operating system’s keychain. If macOS asks for keychain access, choose Always Allow. If your keychain is locked when Qualia needs a stored key, the key shows as not configured. Your saved keys are intact. Unlock the keychain and reconnect, or enter the key again. A locked keychain never blocks saving a key.