Provider Fallback
Configure multiple LLM providers. Mercury tries them in order and falls back automatically. When a provider fails, Mercury tries the next one and remembers the last successful provider.
Session Model Switching
You can switch the active provider/model at runtime without restarting Mercury:
/models— shows configured providers and current active model/models use <provider>— switches the active session model/models doctor— points to setup flow for adding/configuring providers
This is a session-level switch for the running process. Use mercury doctor to change persisted defaults.
Supported Providers
API Key Providers
| Provider | Default Model | API Key | Configuration |
|---|---|---|---|
| DeepSeek | deepseek-chat | DEEPSEEK_API_KEY | Default provider, cost-effective |
| OpenAI | gpt-4o-mini | OPENAI_API_KEY | GPT-4o-mini, GPT-4o, o3, etc. |
| Anthropic | claude-sonnet-4-20250514 | ANTHROPIC_API_KEY | Claude Sonnet, Haiku, Opus |
| Grok (xAI) | grok-4 | GROK_API_KEY | OpenAI-compatible endpoint |
| Ollama Cloud | gpt-oss:120b | OLLAMA_CLOUD_API_KEY | Remote Ollama models via API |
| Ollama Local | gpt-oss:20b | No key needed | Local Ollama instance (127.0.0.1:11434) |
| Atomic Chat | Configurable | No key needed | Local Atomic Chat OpenAI API (127.0.0.1:1337/v1) |
| OpenAI Compatible | Configurable | OPENAI_COMPAT_API_KEY | Any OpenAI-compatible server |
OAuth Providers (No API Key Needed)
These providers authenticate through your browser using OAuth device flow — no API key required.
| Provider | Default Model | Subscription Required | Configuration |
|---|---|---|---|
| ChatGPT Web | gpt-5.4-mini | ChatGPT Plus or Pro | Uses your ChatGPT subscription |
| GitHub Copilot | gpt-4o | GitHub Copilot | Uses your Copilot subscription |
ChatGPT Web (ChatGPT Plus/Pro)
Use your existing ChatGPT Plus or Pro subscription as a Mercury provider. No API key or separate billing — it runs through the same backend as chatgpt.com.
Setup
- Run
mercury doctor(or first-timemercurysetup) - Select OpenAI from the provider list
- Choose ChatGPT Plus/Pro (OAuth — use your subscription)
- A browser window opens — sign in with your OpenAI account and enter the device code shown in the terminal
- Mercury fetches available models from your account and lets you pick a default
How It Works
- Authenticates via OpenAI's device flow OAuth (same flow used by the Codex CLI)
- Uses the ChatGPT Responses API at
chatgpt.com/backend-api/codex - Session tokens are stored locally at
~/.mercury/chatgpt-session.json - Access tokens auto-refresh when they expire — no manual re-authentication needed
Available Models
Models are fetched from your account. Typical models available on the codex endpoint include:
gpt-5.5,gpt-5.4,gpt-5.4-mini,gpt-5.3-codex,gpt-5.2
Only models available on the codex/responses endpoint work with this provider. Some models like gpt-4o, o3, and o4-mini are not available through this endpoint.
Environment Variables
| Variable | Default | Description |
|---|---|---|
CHATGPT_WEB_ENABLED | false | Enable the ChatGPT Web provider |
CHATGPT_WEB_MODEL | gpt-5.4-mini | Default model to use |
GitHub Copilot
Use your GitHub Copilot subscription as a Mercury provider. Authenticates through GitHub OAuth and accesses models through the Copilot API.
Setup
- Run
mercury doctor(or first-timemercurysetup) - Select GitHub Copilot from the provider list
- A browser window opens — sign in with your GitHub account and enter the device code shown in the terminal
- Mercury fetches available models from the Copilot API and lets you pick a default
How It Works
- Authenticates via GitHub's device flow OAuth
- Exchanges the GitHub token for a short-lived Copilot API token (auto-refreshed every ~30 minutes)
- Uses the Copilot API endpoint with OpenAI-compatible requests
- Session stored locally at
~/.mercury/github-session.json - GitHub OAuth tokens don't expire — they remain valid until revoked on github.com
Available Models
Models are fetched dynamically from the Copilot API. Typical models include:
claude-sonnet-4.6,gpt-4o,gpt-5.4,claude-opus-4.6,gpt-4.1,gpt-4o-mini,gemini-3.1-pro-preview
GitHub Copilot provides access to models from OpenAI, Anthropic, and Google — all through a single subscription. This makes it one of the most versatile provider options.
Environment Variables
| Variable | Default | Description |
|---|---|---|
GITHUB_COPILOT_ENABLED | false | Enable the GitHub Copilot provider |
GITHUB_COPILOT_MODEL | gpt-4o | Default model to use |
GitHub Copilot must be active on your GitHub account. If the Copilot token exchange fails, Mercury will show: "Is GitHub Copilot enabled for your account?"
Configuring Providers
Run mercury doctor and enter API keys for the providers you want to use. For OAuth providers (ChatGPT Web, GitHub Copilot), the setup flow opens your browser for authentication — no keys to copy/paste.
You can also set environment variables directly or edit ~/.mercury/mercury.yaml.
Each provider has env vars for its API key, base URL, and model. For example, DeepSeek uses DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL, and DEEPSEEK_MODEL. Ollama Local requires no API key — just set OLLAMA_LOCAL_ENABLED=true and OLLAMA_LOCAL_MODEL to your preferred local model. Atomic Chat uses ATOMIC_CHAT_ENABLED=true, ATOMIC_CHAT_BASE_URL (default http://127.0.0.1:1337/v1), and ATOMIC_CHAT_MODEL.