Reference
Credentials
Configure provider API keys and optional GitHub authentication.
Which key does each command use?
| Capability | Keys |
|---|---|
search |
One or more of BRAVE_API_KEY, TAVILY_API_KEY, EXA_API_KEY |
map-site and normal webpage extraction |
FIRECRAWL_API_KEY |
Alexandria research, inspect, execute |
FIRECRAWL_API_KEY |
| GitHub-native reads | Optional GH_TOKEN or GITHUB_TOKEN |
You can use the plural form of each provider variable (BRAVE_API_KEYS, TAVILY_API_KEYS, EXA_API_KEYS, and FIRECRAWL_API_KEYS) to configure multiple keys from independent accounts. Those keys are rotated based on available capacity.
For Firecrawl Alexandria paid executions, WebCTX deliberately uses the singular FIRECRAWL_API_KEY if set, or the first plural key otherwise. Paid operations do not automatically switch accounts on retries, to avoid duplicate charges or invalid idempotency replays.
Environment or .env.local
For a simple local setup, add only the keys you need:
BRAVE_API_KEY=your-brave-key
EXA_API_KEY=your-exa-key
TAVILY_API_KEY=your-tavily-key
FIRECRAWL_API_KEY=your-firecrawl-key
WEBCTX_FIRECRAWL_PLAN=free
GH_TOKEN=your-github-token
webctx reads existing environment variables first, then .env.local files near the installed binary or current working directory, then macOS Keychain values. Existing variables are not overwritten. Keep .env.local out of version control.
WEBCTX_FIRECRAWL_PLAN selects the rate-limit schedule for all Firecrawl accounts configured in that WebCTX process. Accepted values (case-insensitive): free, hobby, standard, growth, scale. Free is the default; an unrecognized name also conservatively uses Free. Use the same setting for your CLI processes and for your Origo MCP hosting environment. If your API keys belong to teams on different plans, run those accounts in separate processes with matching configurations. Promotional and student credits do not change the team plan’s rate limits.
Plural variables accept comma-separated keys, lines, or JSON arrays:
TAVILY_API_KEYS=account-one-key,account-two-key
FIRECRAWL_API_KEYS=another-team-key,third-team-key
The corresponding singular key joins that provider’s pool, with exact duplicates removed. Your provider’s credit allowance still applies to each account independently.
macOS Keychain
You can add or remove supported provider keys without putting them in shell arguments or plaintext files:
webctx keys list
pbpaste | webctx keys add exa --stdin
pbpaste | webctx keys add firecrawl --stdin
webctx keys remove exa 1
keys add reads one key from standard input. The keys remove number selects a managed Keychain key, newest first; it does not remove a singular environment variable. keys list and webctx status show counts only, never secrets.
On Linux and Windows, use environment variables or .env.local for additional credentials. A macOS Keychain entry named after an environment variable, under service webctx, can also supply a singular key or GH_TOKEN.
Search providers
webctx status
webctx providers disable exa
webctx providers enable exa
Disabled providers are not queried, even when keys are configured. Provider settings are saved to webctx/config.json in the OS user config directory, or the path set by WEBCTX_CONFIG_FILE. status checks local configuration, not actual provider availability or credit balances.
GitHub authentication
Most public repository, file, issue, PR, release, and Gist reads work without a token. Set GH_TOKEN or GITHUB_TOKEN for higher GitHub API capacity or for features such as blame, Discussions, some Actions logs, richer PR review state, and private resources your token can access. GH_TOKEN takes precedence when both are set.
Fine-grained tokens may lack permissions for some endpoints. For selected public GitHub reads, webctx may retry anonymously when a narrow token is rejected. It does not bypass GitHub’s permission model, and native GitHub rate limits/private-resource errors remain visible.
Related reference
- Rate limits and concurrency explains per-key admission, fallbacks, and quotas.
- GitHub URL reference lists native routes and authentication caveats.
- Troubleshooting covers missing keys and provider failures.