Sign in to Qualia
Use Settings > General > Account to Sign in through your browser or Sign out. You can also sign in from the notice above chat.Manage sessions
Choose Manage sessions in Settings > General > Account, or open Settings > Security in Qualia Cloud. Choose Sign out beside a desktop or terminal session to end its access, or Sign out all to end every one.Google Gemini API Key
Add a Google Gemini API key to use Gemini models directly. Get your key from the Google AI Studio.Custom provider endpoints
Enterprise BYOK deployments can route provider calls to a custom OpenAI, Anthropic, or Google Gemini compatible endpoint. In Settings > Models > Provider access, choose the provider auth mode, add the provider API key when needed, and set the matching base URL. Each provider is routed independently. Choose Quadrillion proxy to use your Qualia account for that provider. On an enterprise deployment, it uses your deployment activation. The status line above each provider reports which route is in effect. Leave the base URL blank to use the provider’s default endpoint. Include any required path prefix in the URL, such as/v1 for OpenAI-compatible endpoints.
Use an http or https base URL, including any required path prefix. 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, configure the matching provider API key plus the gateway base URL.
Model ID aliases
Self-hosted endpoints sometimes serve a model under an internal ID that differs from the catalog’s (for example,claude-fable-5 deployed as claude-fable-5-CAVEAT[1m]). Under each provider override, add a Model ID alias mapping the catalog model to the ID your endpoint expects. Requests to your endpoint use the alias, while the model picker, context window, and capability handling continue to follow the catalog entry. Aliases never apply when requests route through Quadrillion.
Custom headers
Some gateways in front of a provider, such as Portkey or an Azure API Management instance, need HTTP headers the provider’s default client never sends, or expect the key in a different header. Under each provider override, choose Add header under Custom headers, enter each header name and value, and choose Save headers. Every request to that provider’s endpoint then carries those headers.- Custom headers are added to the request; they do not change how the API key is sent. For a gateway that expects the key as a bearer token instead of Anthropic’s
x-api-keyheader, set Anthropic API key header to Authorization: Bearer. The key in the API key field is then sent only asAuthorization: Bearer <key>. - Header values are stored like API keys. After saving, Settings shows only the header names; choose Replace headers to enter new values, or Clear to remove them.
Host,Content-Length,Transfer-Encoding, andConnectionare set by the HTTP client and cannot be overridden.- Custom headers never apply when requests route through Quadrillion.
x-portkey-provider: <provider slug> custom header if your gateway routes by provider.
Short-lived keys from a command
Some gateways, such as TrueFoundry, issue each user a key that expires 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, shown in API key or custom endpoint mode. For example:timeout 30 llmgw get token.
- Qualia runs the command when it first needs a key and keeps using that key. When your endpoint rejects it as unauthorized, Qualia runs the command again and retries the request with the new key.
- The command’s key is used instead of 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. It runs on the machine where Qualia’s backend runs, with that machine’s environment, and has 60 seconds to finish. If it fails, chat shows its exit status and error output.
- This is the same contract as Claude Code’s
apiKeyHelpersetting, so a helper written for Claude Code works unchanged. - For a TrueFoundry gateway, set the base URL to your gateway’s
/api/llmendpoint (for examplehttps://<tenant>.truefoundry.cloud/api/llm) and Anthropic API key header to Authorization: Bearer. TrueFoundry names models<provider account>/<model>, so add a Model ID alias for each model you use, such asclaude-sonnet-5→my-anthropic/claude-sonnet-5. - You can also set it with the
OPENAI_API_KEY_HELPER,ANTHROPIC_API_KEY_HELPER, orGEMINI_API_KEY_HELPERenvironment variable. - API key commands are not available in Qualia Cloud. On a shared self-hosted deployment, only the operator can set one, through the environment variable, because the command runs on the server.
Azure endpoints
For Azure OpenAI or Anthropic models in Azure Foundry, set the provider auth mode to Azure Entra ID and enter the Azure endpoint URL. If your Azure deployment authenticates with a key instead, choose Azure (API key) and paste the provider key alongside the endpoint URL. Azure Entra ID uses credentials already available on the host, such as managed identity, Azure CLI login, or service-principal values (AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET). Leave the Entra scope blank unless your administrator gives you a custom scope.
Managing keys
- Saved keys appear as masked hints; you cannot reveal the saved value
- Focus a key field to enter a replacement, which saves automatically
- Keys persist across sessions
- Remove a saved key with its Clear credential trash button
Sign in to the quad-code terminal app
Press Enter on the welcome screen to sign in through your browser, or use Ctrl+K > Account later. Press M to manage sessions. To sign in from another device, press P and paste the sign-in token back into the terminal.Where your keys are stored
Desktop credentials are encrypted and protected by your operating system’s keychain. If macOS requests keychain access, Always Allow remembers access for the current app. Use the import workflow below to copy saved keys to a remote connection. If no keychain is available, credentials are saved in a file readable by your user account. On Linux, Qualia uses the keyring only when it runs inside a local desktop session, because its unlock prompt appears on that machine’s screen. When you reach Qualia over SSH or a port forward, or run it on a machine without a display, credentials go to the file automatically. To use keychain protection on a Linux desktop, create and unlock a default keyring in Passwords and Keys and restart Qualia. If Qualia warns that saved keys are unavailable, unlock the keychain and reconnect. You can also enter a key again to continue. A notice below the titlebar tells you when credentials are stored in a file. Choose Don’t show again on either notice to hide it for good. Neither notice appears over SSH, on a machine without a display, or whenQUALIA_CREDENTIAL_STORE=file is set, because the file is the expected store there. Keys saved while Qualia ran in a desktop session stay in that session’s keychain vault; reopen Qualia in that desktop session to reach them, or enter them again.
In Qualia Cloud, keys are encrypted and private to your account. Desktop and CLI share saved keys.
Import keys from this computer
When you connect the desktop app to a remote backend with missing keys or different preferences, a banner offers Review. In Import settings from this computer, review the proposed changes and select Import. Saved keys are read from your computer’s credential store, and their values are not shown in the dialog. Existing remote keys are left unchanged.Keys in the Qualia CLI
Usequalia login to sign in through your browser, or qualia login --no-browser to sign in from another device. qualia config set stores provider credentials without echoing their values; an empty value clears the saved credential. qualia config list lists public preferences and masked hints, excluding secret values. Configure custom private values through an environment profile.
Troubleshooting
Invalid key errors
- Verify the key is copied correctly without extra spaces
- Check that the key is active in the provider’s dashboard
- Some keys have usage limits — verify you haven’t exceeded them
qualia login in the CLI.
Out of credits
Qualia names the account that ran out, so you know who can fix it.- Using your own provider key: the message points at your provider account. Add credits or update billing with that provider, then retry.
- Using Quadrillion’s API: the message points at your Qualia plan — see Account usage limits. If it instead 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 Settings > General > Account, or your provider credentials in Settings > Models > Provider access.
- Some models require specific account access or waitlist approval.