atrium — Docs
docs/customization/adapter-env.md

Per-adapter environment variables and API keys

Configure adapter environment variables, paste .env values, and store API credentials securely.

atrium can inject environment variables into panes running a specific adapter. This is useful for adapter-specific tuning that should not leak into other terminals — authentication keys, per-adapter feature flags, or TTY quirks like Claude Code's CLAUDE_CODE_NO_FLICKER.

For a custom API endpoint, use Settings → Providers to manage its key, protocols, and models together.

Setting variables from the UI

The fastest path is the gear icon on any adapter's launcher tile — it opens the adapter's settings dialog with the environment variables editor front and center. The same dialog is reachable from Settings → Tools → [adapter] → Environment variables.

The editor is a table of keys and values:

  • Add row to declare a new variable.
  • Delete row icon on each row.
  • Value field — masked when the key looks like a secret (*_KEY, *_TOKEN, *_SECRET, *_PASSWORD), with a show/hide toggle.
  • Paste a .env block into any key field to expand it into rows in one gesture. Atrium parses KEY=value, export KEY=value, quoted values (single or double), and strips # comment lines and trailing # comment tails on unquoted values. Multi-line values are not supported; everything else round-trips cleanly.
Changes are saved immediately. Shells that are currently running receive a USR1 signal, re-source ~/.atrium/shell/env.sh, and pick up the new values — you do not need to press Enter or relaunch the agent for env changes to apply. Note that most adapters cache environment at launch, so runtime changes take effect on the next tool call or on the next resume.

Saved settings

Use the editor to save environment variables. atrium persists them in its app settings. Names that identify credentials, including *_KEY, *_TOKEN, *_SECRET, and *_PASSWORD, are saved as references to the host's operating system credential store. Replace a value through the editor; do not edit a credential reference by hand.

Precedence

Environment resolution order for a pane running an adapter:

  1. System environment (the user's shell defaults).
  2. atrium's own variables (ATRIUM_CLI_PATH, ATRIUM_PANE_ID, etc.).
  3. Variables from the adapter environment editor.
  4. Launcher-specific flags (from --adapter-flags on the CLI, or the launcher option fields in the UI).
Later entries win. To override a system variable only for a specific adapter, set it in adapterEnvVars.<adapter>.

Useful variables by adapter

Claude Code

  • CLAUDE_CODE_NO_FLICKER=1 — smoother partial-output rendering inside atrium. Set by default.
  • ANTHROPIC_API_KEY — authentication for the Claude API. Also respected via claude login.

Codex

  • OPENAI_API_KEY — Codex authentication.

Antigravity

  • GOOGLE_API_KEY / GEMINI_API_KEY — Gemini authentication.

Secrets

Credential values use macOS Keychain, Windows Credential Manager, or the Linux login keyring through secret-tool. The host resolves their references when launching an agent. An unavailable credential store produces an error instead of saving plaintext. Existing settings migrate at startup; previously created backups are not rewritten. Ordinary environment values remain in app settings, and runtime processes receive resolved credentials in their environment.

Variables atrium sets for you

These are always injected and cannot be overridden by user config (overrides are silently dropped if they collide):

  • ATRIUM, ATRIUM_CLI_PATH, ATRIUM_DATA_DIR
  • ATRIUM_PANE_ID, ATRIUM_WORKSPACE_ID, ATRIUM_TAB_ID
  • ATRIUM_HOOK_PORT
  • ATRIUM_TASK_ID, ATRIUM_TASK_RUN_ID (when the pane is bound to a task)
  • ATRIUM_EXISTING_PROMPT_COMMAND (preserves the user's existing bash PROMPT_COMMAND)
  • ATRIUM_REAL_ZDOTDIR, ATRIUM_BOOTSTRAP_ZDOTDIR (zsh integration internals)