API Key Storage

Updated October 23, 2026

crystl stores your API keys in the macOS Keychain and automatically injects them as environment variables into every shell session. No more exporting keys in your .zshrc or .env files.

The page has a new name. Keys are now in settings, providers & keys, which was called api keys before. It lists hosted provider keys (this page) and, below them, your open-model connections: Ollama, LM Studio, vLLM, or llama.cpp on your own hardware, plus hosted open models behind anthropic-compatible APIs. Both halves work the same way, injecting environment variables into every new shard, and each open-model connection can have its own key.

How it works

When you add an API key to crystl, it:

  1. Saves the key to your macOS Keychain (encrypted at rest by the OS)
  2. Injects the key as an environment variable when any shard starts
  3. Masks the key in the settings UI, showing only the first 6 and last 4 characters

Your keys are always available in your shards without being stored in plaintext config files.

Supported providers

crystl recognizes keys for these providers and sets the correct environment variable automatically:

Provider Environment Variable
Anthropic ANTHROPIC_API_KEY
OpenAI OPENAI_API_KEY
Google AI GEMINI_API_KEY
OpenRouter OPENROUTER_API_KEY

Custom providers

You’re not limited to the four providers above. Add a custom provider to store a key for any service that reads its credential from an environment variable: a self-hosted model, an OpenAI-compatible gateway, or any other tool.

When you add a custom provider, you specify the environment variable name crystl should set (for example DEEPSEEK_API_KEY) and paste the value. crystl saves it to the macOS Keychain and injects it into every new shard exactly like the built-in providers.

Adding a key

  1. Open settings, providers & keys (Cmd + , then navigate to providers & keys)
  2. Select a provider (or add a custom one)
  3. Paste your key
  4. Click Save

The key is stored in macOS Keychain immediately. New shards will pick it up on creation; restart existing shards to load the updated key.

Removing a key

Delete a key from settings, providers & keys. crystl removes it from the macOS Keychain and stops injecting it into new sessions.

When an agent needs a key

Agents in crystl have four commands for keys. All of them print names and statuses, never a value. See the CLI reference for every flag.

  • crystl keys lists the key names the gem knows about, and whether the agent can reach each one.
  • crystl keys where <NAME> answers for one name. resolvable means the agent can use it now: it is set in the shell, saved here, or assigned in one of the gem’s .env files, which the answer names. needs_auth means macOS has not let crystl read your saved keys yet, so the agent asks you to allow it once. unregistered is the only answer that means the key is really missing.
  • crystl keys note <NAME> records where a key lives, who owns it, or what happened when the agent used it. The next agent reads the note instead of searching. Notes hold paths and sentences. crystl masks anything shaped like a credential, and refuses a note only when it holds a value in a known secret format. A note that only looks like a key, such as a Stripe account ID, is saved with a warning.
  • crystl keys request <NAME> --reason "<why>" raises a card on your Mac when a key is missing. It names the shard that asked and shows the agent’s reason as a quote. Type the value into the masked field and press save to Keychain, or press not now. The value goes to the Keychain like a key added here, and the agent is told only stored or declined.

A key saved from a card is set in every shard you open afterwards. The shard that asked keeps the environment it started with, because a running process cannot be changed from outside. Your phone gets a notice naming the key, with no field to type into.

The keys feature page shows the card in action.

Security

Keys are stored using the macOS Keychain Services API, the same system Safari and other native apps use for credential storage. crystl never writes keys to disk in plaintext. They exist only in memory within active shell sessions.

Availability

API key storage is available on all plans, including Free.