Skip to content
Mastery HQ Help

API keys and the .env file

Mastery HQ keeps agent API keys in one local .env file. Paste your keys once and every agent it launches stays signed in perpetually — keys are forwarded to the agent CLI as environment variables and never stored anywhere else or read back by the app beyond checking which keys are set.

The keys

Section titled “The keys”
Variable Used by
ANTHROPIC_API_KEY Claude Code
OPENAI_API_KEY Codex
CURSOR_API_KEY Cursor Agent
OPENROUTER_API_KEY OpenRouter agents + extra Council/Benchmark models
GEMINI_API_KEY Gemini CLI (incl. native video attachments)
XAI_API_KEY Grok — the xAI voice and Hermes brain option

(CLIs signed in through their own login flow don’t need a key here at all.)

Steps

Section titled “Steps”
  1. Open Settings → Agents and scroll to Agent API keys (.env). Each key shows a dot: set or not set — values are never displayed.
  2. Click Open .env file (or Create .env file the first time) — it opens the file’s location. Add lines like ANTHROPIC_API_KEY=sk-ant-…, save.
  3. Back in Settings, click Recheck keys.
  4. Open a fresh agent window — running agents keep their old environment.

Multiple accounts & rate-limit failover

Section titled “Multiple accounts & rate-limit failover”

Claude Code and Codex support multiple signed-in accounts with automatic failover (Settings → Agents → Accounts & rate-limit failover):

  1. Type a label (e.g. Personal) and click Add — the account is a folder that CLI will keep its own login in (CLAUDE_CONFIG_DIR / CODEX_HOME); no password or key touches Mastery HQ.
  2. Click Copy login cmd, run it in a terminal, and sign in once.
  3. Leave Auto-switch accounts on rate limit on. When a run hits its usage limit, the limited account rests until its window resets (read from the CLI’s own notice when possible), the next available account takes over, and the task re-runs on the spot — with a transcript note, a toast, and an Audit Log entry. The switch applies everywhere runs happen: agent windows, Hermes plans, loops, and judges.

The account switch starts a fresh conversation on the new account — a CLI’s session history lives inside its account folder, so continuity can’t cross accounts.

Good to know

Section titled “Good to know”
  • A project-level .env inside a workspace folder overrides these global keys for agents working there.
  • While Streaming Mode is on, Open .env file is disabled (it would put your keys one click from the stream) and key-shaped strings are masked anywhere they’d render.
  • The Setup wizard (Settings → Setup) writes to this same file — use whichever is more convenient.