Credentials

How Credentials Are Resolved¶

Rusty resolves API keys through a tiered chain, checking each source in order. The first non-empty value found is used.

Resolution Order¶

Environment Variables

RUSTY_API_KEY is checked first, then OPENAI_API_KEY. Empty strings are treated as absent.
OS Keyring

If credential_store is set to "keyring" in settings, Rusty reads from the system keyring:
- macOS: Keychain Access
- Windows: Credential Manager
- Linux: Secret Service (GNOME Keyring, KWallet)
Settings File

The api_key field in ~/.rusty/settings.json is used as a final fallback.

Credential Store Options¶

Keyring (Recommended)¶

Stores the API key in the operating system's secure credential store. This is the default and recommended option.

{
  "credential_store": "keyring"
}

The keyring is managed automatically by the setup wizard. You can also manage it programmatically:

# Check if keyring is available
rusty --setup

Settings File¶

Stores the API key in plaintext in ~/.rusty/settings.json. Use this if your platform does not have a keyring available (e.g., headless Linux without a desktop environment).

{
  "credential_store": "settings_file",
  "api_key": "sk-..."
}

Warning

When using settings_file mode, the API key is stored in plaintext. Ensure appropriate file permissions on ~/.rusty/settings.json.

Multi-Provider Setup¶

If you switch between providers, you can store separate credentials using environment variables:

export OPENAI_API_KEY=sk-openai-...
export RUSTY_API_KEY=sk-other-...

RUSTY_API_KEY always takes precedence over OPENAI_API_KEY.