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 withqd_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 thequalia 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.
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
httporhttpsURL, and include any required path prefix, such as/v1for 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.
Model ID aliases
A self-hosted endpoint sometimes serves a model under a different ID than Qualia’s catalog uses. For example, it might serveclaude-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, orConnection. - Custom headers never apply when requests route through Qualia’s servers.
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:
- Paste the Portkey key as the Anthropic API Key.
- Set Anthropic API key header to Authorization: Bearer.
- 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
apiKeyHelpersetting works unchanged.
- Set the base URL to your gateway’s
/api/llmendpoint, such ashttps://[TENANT].truefoundry.cloud/api/llm. - Set Anthropic API key header to Authorization: Bearer.
- Add a Model ID alias for each model you use, because TrueFoundry names models
[PROVIDER_ACCOUNT]/[MODEL]. For example, mapclaude-sonnet-5tomy-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.
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.

